Remote Two/3 WebSocket Core-APIย 0.29.2-beta

The Unfolded Circle WebSocket Core-API for Remote Two/3 (UCR WS Core-API in short) allows to interact with the Unfolded Circle remote-core service and take control of most of its features. It is a subset of the UCR REST Core-API, but provides additional asynchronous event messages.

API message status legend:

Icon Description
๐Ÿ’ก Idea, not yet official part of API definition.
๐Ÿšง Planned feature and most likely not (fully) implemented in the initial release.
๐Ÿ‘ท API definition is work in progress, not ready yet for implementation.
๐Ÿ” API definition review & implementation.
๐Ÿงช API has been implemented in the UC Remote and is currently being tested.
๐Ÿš€ Ready to use - feedback welcomed.

Overview

The Unfolded Circle Remote Core-APIs consist of:

The remote-core service acts as WebSocket server. Whenever the remote enters standby it may choose to disconnect client connections.

The focus of the Core-APIs is to provide all functionality for the UI application and the web-configurator.
They allow to interact with the Unfolded Circle remote-core service and take full control of its features.

The Core-APIs may also be used by other external systems and integration drivers, if specific configuration or interaction features are required, which are not present in the UCR Integration-API.

๐Ÿšง Missing Features

This API is a work-in-progress and does not yet contain all functionality of the REST API.

The following features will be continuously added (in no particular order):

  • Matching features of the REST Core-API (except file up & download):
    • Activity management
    • Infrared code management
  • Static network configuration

Please check the core-api GitHub issues for the current state.

API Versioning

The API is versioned according to SemVer.
The initial public release will be 1.0.0 once it is considered stable enough with some initial integration implementations and developer examples.

Any major version zero (0.y.z) is for initial development and may change at any time!
I.e. backward compatibility for minor releases is not yet established, anything MAY change at any time! We try avoiding it, but it might still happen...

WebSocket Connection

Authentication

Interaction with the API requires an API-key, user account or a session cookie (see login operation in the REST Core-API).

If the session cookie is sent with the WebSocket upgrade request, the connection is automatically authenticated. This is recommended when using a web browser as client.

Basic authentication

A user account can be used with basic authentication in the WebSocket upgrade.

  • Header name: Authentication.
  • Value: Basic + base64 encoded value of ${username}:${password}

API-key authentication

If the session based login is not possible or the client needs to use an API-key, then the preferred way to establish an authenticated WebSocket connection is to provide the API-key in the header of the WebSocket connection.

  • Header name: API-KEY.
  • Value: API key

API keys can be created with the REST API and the auth/api_keys endpoints.

Message based authentication

If the client cannot provide the API-key in the connection setup (e.g. a web browser), the server will send the auth_required message right after the connection is established.

  • The client must reply with the auth message containing the API-key.

    • All other messages will be ignored, until the client successfully authenticates itself.
    • The server will close an unauthenticated connection after a timeout of 15 seconds.
  • The server replies with the authentication event including the result code of the authentication.

    • 200: authentication succeeded, API can be used.
    • 401: invalid authentication and the connection will be closed.
  • #integration
  • #entity
  • #profile
  • #dock
  • #wifi

Servers

  • localhost:8080wstest

    Local test server.

    Security:
    • HTTP API key
      • Name: API-KEY
      • In: header

      The API-key can be provided in header key API-KEY.

      • If this header is not provided, the server will send the auth_required event after connection and the client must authenticate with the auth message.
    • HTTP
      • Scheme: basic

      To login with a user account, basic authentication can be used for the WebSocket upgrade. As an alternative, a session based login with the REST API can be performed. The session cookie will automatically authenticate the Websocket connection.

  • localhost:8443wsstest-wss

    Local test server.

    Security:
    • HTTP API key
      • Name: API-KEY
      • In: header

      The API-key can be provided in header key API-KEY.

      • If this header is not provided, the server will send the auth_required event after connection and the client must authenticate with the auth message.
    • HTTP
      • Scheme: basic

      To login with a user account, basic authentication can be used for the WebSocket upgrade. As an alternative, a session based login with the REST API can be performed. The session cookie will automatically authenticate the Websocket connection.

Operations

  • PUB /ws

    Core-API for clients to interact with the remote.

    Operation IDpubRemoteMessage
    • #core

    Accepts one of the following messages:

    • #0auth

      ๐Ÿงช Authenticate a connection.

      Sent by the client right after establishing a connection if header authentication cannot be used, or after an auth_required request by the server.

      object allOf
      uid: authRequestMsg

      Examples

    • #1ping

      ๐Ÿš€ Application level based ping to determine whether connection is alive.

      Client can ping the server to determine whether connection is alive. Server responds with pong.

      This is an application level ping as opposed to the standard WebSocket ping frames. This is only required if a client framework doesn't support WebSocket ping frames!
      Additional payload data may be included in msg_data which will be echoed by the server. E.g. a client timestamp to calculate round trip times.

      object allOf
      uid: ping

      Examples

    • #2version

      ๐Ÿš€ Get version information.

      object allOf
      uid: versionMsg

      Examples

    • #3system

      ๐Ÿš€ Get system information.

      Get hardware information about the device like serial number, model number and hardware revision.

      object allOf
      uid: getSystemInfoMsg

      Examples

    • #4system_cmd

      ๐Ÿงช Perform a system command like reboot or power-off.

      The following system commands can be executed:

      • STANDBY: Put the device into standby mode.
      • REBOOT: Reboot the device.
      • POWER_OFF: Switch off the device
      • RESTART: Restart all applications.
      • RESTART_UI: Restart the ui application.
      • RESTART_CORE: Restart the core service application.

      The server will respond with a result message and a status code of the request.
      For status code 200 the WebSocket connection will be closed and the command executed.

      object allOf
      uid: systemCmdMsg

      Examples

    • #5get_factory_reset_token

      Get factory reset token.

      Get a factory reset token to perform a complete factory reset of the remote.

      The token will be valid for 60 seconds. Afterwards, a new token must be requested.
      Whenever a new token is requested, any old tokens will be invalidated.

      object allOf
      uid: getFactoryResetTokenMsg

      Examples

    • #6factory_reset

      Perform a factory reset.

      A factory reset removes all configuration data and puts the device into a clean state.

      โš ๏ธ Warning: All user data will be erased and won't be recoverable!

      A reset token must be requested first and provided to perform a factory reset.

      object allOf
      uid: factoryResetMsg

      Examples

    • #7set_api_access

      Enable or disable API access.

      Enable / disable API access for web-configurator. If the account gets disabled, all active sessions are closed and WebSocket connections disconnected.
      The server will respond with a result message and a status code of the request.

      object allOf
      uid: setApiAccessMsg

      Examples

    • #8get_api_access

      Get API access status.

      The server will respond with an api_access message.

      object allOf
      uid: getApiAccessMsg

      Examples

    • #9check_system_update

      ๐Ÿงช Check if system update is available.

      Returns the known available system updates.

      System update checks are run automatically (if not disabled in settings). Use the force_update flag to force an update check.

      object allOf
      uid: checkSystemUpdateMsg

      Examples

    • #10update_system

      ๐Ÿงช Perform system update.

      Start a system update with the given update_id parameter. Use latest to use the latest available system update.

      The system update will be started if:

      • the system update has been downloaded already (download state is DOWNLOADED).
      • the device has at least 50% battery charge.

      If the system update is started, the response message contains state: START. In case there's not enough battery, 503 service unavailable is returned. It is recommended to perform the update while the remote is charging in the docking station.

      The progress of the system update can be retrieved with the get_system_update_progress message, or by listening to the software_update event messages.

      If the system update hasn't been downloaded yet (download state is PENDING or ERROR), this operation will only start the download and return state: DOWNLOAD. Once successfully downloaded, it can be installed by this request message again.

      The download process emits software_update progress event messages with event_type: PROGRESS and state: DOWNLOAD. The payload fields download_bytes, download_percent and update_id are set.

      • A successful download is indicated with download_percent: 100, without the download_bytes field.
      • The state is set to FAILURE if a download fails.
      • Depending on download speed, download_percent might skip certain values or report the same value multiple times.
      • The famous last percent will take longer due to image validation.

      Example download progress events:

      • Download progress event:
      {
        "kind": "event",
        "msg": "software_update",
        "cat": "REMOTE",
        "ts": "2024-09-30T16:25:18.668395688Z",
        "msg_data": {
          "event_type": "PROGRESS",
          "progress": {
            "download_bytes": 256734720,
            "download_percent": 97,
            "state": "DOWNLOAD",
            "update_id": "some-id"
          },
          "update_id": "some-id"
        }
      }
      
      • Final success event:
      {
        "kind": "event",
        "msg": "software_update",
        "cat": "REMOTE",
        "ts": "2024-09-30T16:25:34.229442566Z",
        "msg_data": {
          "event_type": "PROGRESS",
          "progress": {
            "download_percent": 100,
            "state": "DOWNLOAD",
            "update_id": "some-id"
          },
          "update_id": "some-id"
        }
      }
      
      object allOf
      uid: updateSystemMsg

      Examples

    • #11get_system_update_progress

      ๐Ÿงช Get system update progress.

      This is a manual request for the update progress if the system update event messages cannot be used.

      object allOf
      uid: getSystemUpdateProgressMsg

      Examples

    • #12get_power_mode

      ๐Ÿงช Get current power mode and battery information.

      object allOf
      uid: getPowerModeMsg

      Examples

    • #13set_power_mode

      ๐Ÿงช Change the current power mode.

      object allOf
      uid: setPowerModeMsg

      Examples

    • #14get_battery_charger

      ๐Ÿ‘ท Get battery charger information.

      Device features:

      • DOCK_CHARGING: device can be charged in docking station (UCR2, UCR3).
      • WIRELESS_CHARGING: device has wireless charging support (UCR3).
      object allOf
      uid: getBatteryChargerMsg

      Examples

    • #15update_battery_charger

      ๐Ÿ‘ท Enable or disable wireless charging.

      object allOf
      uid: updateBatteryChargerMsg

      Examples

    • #16get_standby_inhibitors

      ๐Ÿงช Get standby inhibitors.

      Automatic system standby can be prevented with "standby inhibitors". For example during integration setup or as a user option for activities.

      There are two types of inhibitors:

      • Temporary inhibitors set a delay value for which the device doesn't go into standby. After the delay and the idle timeouts have expired, the remote goes into standby and the temporary inhibitor will be removed.
      • Blocking inhibitors will prevent the device to go into standby until the inhibitor is removed by the client.

      Note: temporary inhibitors will only be checked and removed during standby events. As long as the device is active, they may still appear in the result.

      object allOf
      uid: getStandbyInhibitorsMsg

      Examples

    • #17create_standby_inhibitor

      ๐Ÿงช Create a standby inhibitor.

      object allOf
      uid: createStandbyInhibitorMsg

      Examples

    • #18del_standby_inhibitor

      ๐Ÿงช Remove a standby inhibitor.

      object allOf
      uid: delStandbyInhibitorMsg

      Examples

    • #19del_all_standby_inhibitors

      ๐Ÿงช Remove all standby inhibitors.

      object allOf
      uid: delAllStandbyInhibitorsMsg

      Examples

    • #20get_ambient_light

      ๐Ÿ” Get current ambient light intensity.

      object allOf
      uid: getAmbientLightMsg

      Examples

    • #21reset_configuration

      ๐Ÿงช Reset all settings to default values.

      object allOf
      uid: resetConfigurationMsg

      Examples

    • #22get_configuration

      ๐Ÿงช Get all system settings.

      object allOf
      uid: getConfigurationMsg

      Examples

    • #23get_button_cfg

      ๐Ÿงช Get button settings.

      object allOf
      uid: getButtonCfgMsg

      Examples

    • #24set_button_cfg

      ๐Ÿงช Modify button settings.

      object allOf
      uid: setButtonCfgMsg

      Examples

    • #25get_device_cfg

      ๐Ÿงช Get remote device settings.

      object allOf
      uid: getDeviceCfgMsg

      Examples

    • #26set_device_cfg

      ๐Ÿงช Modify remote device settings.

      object allOf
      uid: setDeviceCfgMsg

      Examples

    • #27get_display_cfg

      ๐Ÿงช Get display settings.

      object allOf
      uid: getDisplayCfgMsg

      Examples

    • #28set_display_cfg

      ๐Ÿงช Modify display settings.

      object allOf
      uid: setDisplayCfgMsg

      Examples

    • #29get_features_cfg

      ๐Ÿงช Get feature flag settings.

      object allOf
      uid: getFeaturesCfgMsg

      Examples

    • #30set_features_cfg

      ๐Ÿงช Modify a feature flag.

      object allOf
      uid: setFeaturesCfgMsg

      Examples

    • #31get_haptic_cfg

      ๐Ÿงช Get haptic settings.

      object allOf
      uid: getHapticCfgMsg

      Examples

    • #32set_haptic_cfg

      ๐Ÿงช Modify haptic settings.

      object allOf
      uid: setHapticCfgMsg

      Examples

    • #33get_localization_cfg

      ๐Ÿงช Get localization settings.

      object allOf
      uid: getLocalizationCfgMsg

      Examples

    • #34set_localization_cfg

      ๐Ÿงช Modify localization settings.

      object allOf
      uid: setLocalizationCfgMsg

      Examples

    • #35get_timezone_names

      ๐Ÿงช Get all available time zone names.

      object allOf
      uid: getTimezoneNamesMsg

      Examples

    • #36get_localization_countries

      ๐Ÿงช Get available countries for the localization configuration.

      object allOf
      uid: getLocalizationCountriesMsg

      Examples

    • #37get_localization_languages

      ๐Ÿงช Get stored translations or request available translations from the UI.

      The available translations are provided from the UI application.
      Future UI versions might provide new or updated translations.

      If this request is sent to the UI application, the response is stored in the remote-core until new information is available from the UI.

      If this request is received, the stored configuration from the UI application is returned. E.g. the web-configurator requires the available translations.

      object allOf
      uid: getLocalizationLanguagesMsg

      Examples

    • #38localization_languages

      ๐Ÿงช Available translations response.

      object allOf
      uid: localizationLanguagesMsg

      Examples

    • #39get_network_cfg

      ๐Ÿงช Get network settings.

      object allOf
      uid: getNetworkCfgMsg

      Examples

    • #40set_network_cfg

      ๐Ÿ” Modify network settings.

      Change one or multiple network settings.

      โš ๏ธ The ws configuration object is an expert setting intended for support issues. Those settings may not be exposed in a user frontend.

      • The ws object is only returned, after it has been set manually.
      • Settings stay persisted for PATCH requests not containing the ws key.
      • Return and apply current system settings: send a PATCH request with an empty object: `"ws": {}".
      • The ws settings can only be removed with a configuration reset: DELETE /cfg
      • Modifying any ws settings requires a system reboot.
      object allOf
      uid: setNetworkCfgMsg

      Examples

    • #41get_software_update_cfg

      ๐Ÿงช Get software update settings.

      object allOf
      uid: getSoftwareUpdateCfgMsg

      Examples

    • #42set_software_update_cfg

      ๐Ÿงช Modify software update settings.

      Change one or multiple software update settings.

      If check_for_updates is enabled:

      • the device automatically checks for new updates daily. The check happens during a random time within the OTA window time frame ota_window_start - ota_window_end.
      • if a new update is available, the update metadata is immediately downloaded and the firmware update file is scheduled to download.
      • the firmware file will only download if the remote has at least 50% battery charge.
      • if the remote is not in the dock and suspended, the remote will not automatically wake up and the check will be skipped.

      If auto_update is enabled:

      • once the firmware file is downloaded it will be automatically installed in the next OTA check window.
      • the installation will only start if the remote has at least 50% battery charge.

      OTA window fields:

      • the stored values are used if omitted.
      • default values are set if not configured.
      • the time of day corresponds to the configured timezone.
      • for changing the update window, both start and end times are required, otherwise a default will be used.
      • if the end time is before the start time, the window will spawn over midnight, e.g. 23:00:00 - 01:00:00.

      Optional software update channel & token:

      • the default release channel is used if not configured.
      • the stored values are used if omitted.
      • changing the update channel is intended for closed user groups only.
        โš ๏ธ High chance of breaking changes, bugs and loosing data!
      • other channels than default might require an access token in channel_token.
      • โš ๏ธ Changing the update channel or token requires a device restart, otherwise the automated updates will not use the new channel!
      object allOf
      uid: setSoftwareUpdateCfgMsg

      Examples

    • #43reset_software_update_cfg

      ๐Ÿงช Reset software update settings.

      Set all software update settings to default values and use the default release update channel.

      object allOf
      uid: resetSoftwareUpdateCfgMsg

      Examples

    • #44get_power_saving_cfg

      ๐Ÿงช Get power saving settings.

      object allOf
      uid: getPowerSavingCfgMsg

      Examples

    • #45set_power_saving_cfg

      ๐Ÿงช Modify power saving settings.

      object allOf
      uid: setPowerSavingCfgMsg

      Examples

    • #46get_profile_cfg

      ๐Ÿงช Get profile settings.

      object allOf
      uid: getProfileCfgMsg

      Examples

    • #47set_profile_cfg

      ๐Ÿงช Modify profile settings.

      object allOf
      uid: setProfileCfgMsg

      Examples

    • #48get_sound_cfg

      ๐Ÿงช Get sound settings.

      object allOf
      uid: getSoundCfgMsg

      Examples

    • #49set_sound_cfg

      ๐Ÿงช Modify sound settings.

      object allOf
      uid: setSoundCfgMsg

      Examples

    • #50get_voice_control_cfg

      ๐Ÿ” Get voice control settings.

      object allOf
      uid: getVoiceControlCfgMsg

      Examples

    • #51set_voice_control_cfg

      ๐Ÿ” Modify voice control settings.

      object allOf
      uid: setVoiceControlCfgMsg

      Examples

    • #52get_voice_assistants

      ๐Ÿšง Get available voice assistants.

      object allOf
      uid: getVoiceAssistantsMsg

      Examples

    • #53get_entity_types

      ๐Ÿงช Retrieve supported entity types.

      object allOf
      uid: getEntityTypesMsg
      • #entity

      Examples

    • #54get_entity

      ๐Ÿงช Retrieve a configured entity.

      object allOf
      uid: getEntityMsg
      • #entity

      Examples

    • #55get_entities

      ๐Ÿงช Search and retrieve configured entities.

      Returns all configured entities, optionally filtered by one or multiple entity types or integrations.

      The text search searches in the entity name, entity identifier and integration name.

      Attention: pagination is active and can be parameterized to return more items per page if required.

      object allOf
      uid: getEntitiesMsg
      • #entity

      Examples

    • #56get_available_entities

      ๐Ÿงช Retrieve the available entities provided by an integration.

      โš ๏ธ At the moment it's only possible to retrieve available entities from one integration at a time.

      • filter.integration_id must be specified!
      • available entities can be filtered by one or multiple entity types.
      • the text search searches in the entity name, entity identifier and area.

      Attention: pagination is active and can be parameterized to return more items per page if required.

      object allOf
      uid: getAvailableEntitiesMsg

      Retrieve the available entities provided by the integration instance.

      • #entity

      Examples

    • #57get_entity_commands

      ๐Ÿงช Retrieve the available commands of an entity or entity type.

      The commands can either be retrieved from a specific entity or from an entity type:

      • entity_id: only available commands for the given entity are returned. This depends on the entity's features.
      • entity_type: all commands for the given entity type are returned.

      The returned command identifiers are not the standard command identifiers like on or off, but mapping identifiers like light.on and light.color_temperature for the command structure information returned with get_entity_command_metadata or GET /api/cfg/entity/commands.

      This then allows to build a full command request execute_entity_command message with or without parameters.

      object allOf
      uid: getEntityCommandsMsg
      • #entity

      Examples

    • #58get_entity_command_metadata

      ๐Ÿ” Get entity command definitions.

      Meta-information about the entity commands.

      object allOf
      uid: getEntityCommandMetadataMsg
      • #entity

      Examples

    • #59execute_entity_command

      ๐Ÿงช Execute an entity command.

      Optional command data can be provided in attribute params.

      object allOf
      uid: executeEntityCommandMsg
      • #entity

      Examples

    • #60update_entity

      ๐Ÿงช Update an entity.

      Update one or multiple properties of an entity.

      The updated entity object is returned if the entity could be updated.
      In case of an error the default result message is returned with an error code.

      object allOf
      uid: updateEntityMsg
      • #entity

      Examples

    • #61delete_entity

      ๐Ÿงช Remove a configured entity.

      Delete the configured entity and remove it from all profile pages and groups.

      object allOf
      uid: deleteEntityMsg
      • #entity

      Examples

    • #62delete_entities

      ๐Ÿงช Remove configured entities.

      Unloads and deletes multiple configured entities, either by integration identifier or by entity identifiers. If a deleted entity is still provided from an integration, it can be reused and will show up again as available entity from its integration.

      โš ๏ธ An empty request body array will delete all configured entities!

      All references to the configured entities will be removed from profile pages and groups.

      This is a best effort operation:

      • unknown entity identifiers are ignored, no error is returned

      Deleted entities will trigger an entity_change event with event_type: DELETE. If a large amount of entities are deleted, a single, generic entity_change event might be sent instead (without an entity_id field).

      object allOf
      uid: deleteEntitiesMsg
      • #entity

      Examples

    • #63get_dock_count

      ๐Ÿงช Get total number of configured docks.

      By default only active docks are counted. This can be changed with the active query parameter.

      object allOf
      uid: getDockCountMsg
      • #dock

      Examples

    • #64get_docks

      ๐Ÿงช List configured docks and their connection state.

      Returns all dock configuration with paging. The configuration data is enriched with current connection information. Use the get_dock_count operation to retrieve the total number of defined docking stations.

      By default only active docks are returned. This can be changed with the active query parameter.

      object allOf
      uid: getDocksMsg
      • #dock

      Examples

    • #65create_dock

      ๐Ÿงช Create a new dock configuration.

      Manually create and persist a new dock configuration. This is a low-level operation without configuring and setting up the dock as with the setup operations! To establish a session to the dock, the connect operation must be called afterwards.

      • Error 422 is returned if the given service name in dock_id already exists.
      • If custom_ws_url is not specified, the dock address is resolved through an mDNS service name lookup in dock_id.
      • The active flag specifies if the dock will react to connection requests.
      • Non-active docks will not auto-connect and must be enabled first to be used.
      • Non-active docks won't be visible in the web-configurator.
      • If no token is provided the default token is used! The token is used to authenticate the WebSocket connection once a connection to the dock is established.
      • If model is provided it must be one of the known dock model identifiers: UCD2 or YIO1DOCK.
      object allOf
      uid: createDockMsg
      • #dock

      Examples

    • #66delete_all_docks

      ๐Ÿงช Delete all dock configurations.

      โš ๏ธ All defined dock configurations will be irrevocably deleted!

      Active dock sessions will be disconnected and the persisted dock configurations removed.

      object allOf
      uid: deleteAllDocksMsg
      • #dock

      Examples

    • #67get_dock

      ๐Ÿงช Get dock configuration.

      Returns the dock configuration, enriched with the current session information if a dock connection is established.

      object allOf
      uid: getDockMsg
      • #dock

      Examples

    • #68update_dock

      ๐Ÿงช Change dock configuration like auto-connect or access token.

      Update one or more dock fields.

      • If the dock is in an active connection state, then the name, token and wifi values are persisted in the dock if provided in the request. The request fails with 503 service unavailable if the configuration can't be set in the docking station.
      • An empty custom_ws_url value will remove the custom URL.
      • If the dock is not active, the values are only stored in the remote. A changed token will be used for the next connection attempt.
      object allOf
      uid: updateDockMsg
      • #dock

      Examples

    • #69dock_connection_command

      ๐Ÿงช Start or stop a dock connection.

      Establish or stop a session to a specific or all active docks.

      object allOf
      uid: dockConnectionCommandMsg
      • #dock

      Examples

    • #70delete_dock

      ๐Ÿงช Delete dock configuration.

      โš ๏ธ The dock configuration will be irrevocably deleted!

      An active dock session will be disconnected and the persisted dock configuration removed.

      object allOf
      uid: deleteDockMsg
      • #dock

      Examples

    • #71dock_command

      ๐Ÿงช Send a dock command.

      The following command values are defined:

      • SET_LED_BRIGHTNESS: set the maximum brightness of the front indicator LED. Set the 0..100 percentage as string parameter in the value field.
      • IDENTIFY: identify the dock with blinking the indicator LED.
      • REMOTE_LOW_BATTERY: trigger the low battery status indicator on the dock.
      • REMOTE_CHARGED: trigger the remote charged indicator on the dock.
      • REMOTE_NORMAL: trigger the normal remote operation mode on the dock.
      • REBOOT: reboot the dock.
      • RESET: โš ๏ธ factory reset the dock. Requires administrator privileges.
        The dock configuration will be deleted from the remote.
      object allOf
      uid: dockCommandMsg
      • #dock

      Examples

    • #72get_dock_discovery_status

      ๐Ÿงช Get docking station discovery status.

      Returns the current discovery status and any discovered docks.

      object allOf
      uid: getDockDiscoveryStatusMsg
      • #dock

      Examples

    • #73start_dock_discovery

      ๐Ÿงช Start discovery of new docking stations.

      Start device discovery over Bluetooth and mDNS. Bluetooth or network discovery can be disabled with a query parameter. By default the discovery automatically stops after 30 seconds. Use the get_dock_discovery_status status request to check on discovered devices or stop_dock_discovery to stop discovery.

      By default only new network devices are returned. If a dock is already configured it will be omitted from the results, unless the query parameter new=false is set. Docks with Bluetooth enabled are always returned, since this usually means that the dock needs to be re-configured.

      • If BT is disabled in the remote, the bt parameter is ignored.
      • Emits the WebSocket event dock_discovery with event_type: START when discovery starts.
      • For each discovered device the WebSocket event dock_discovery with event_type: DISCOVER is emitted.
      • This operation clears any old discovered devices and won't be accessible anymore with the GET operation.
      object allOf
      uid: startDockDiscoveryMsg
      • #dock

      Examples

    • #74stop_dock_discovery

      ๐Ÿงช Stop discovery of new docking stations.

      Stops the device discovery. The current discovery status is returned in the response. Already discovered devices won't be returned and can still be retrieved with the get_dock_discovery_status operation.

      Emits the WebSocket event dock_discovery with event_type: STOP.

      object allOf
      uid: stopDockDiscoveryMsg
      • #dock

      Examples

    • #75get_dock_discovery_device

      ๐Ÿงช Get docking station discovery device status.

      Returns the discovered docking station device.

      object allOf
      uid: getDockDiscoveryDeviceMsg
      • #dock

      Examples

    • #76exec_cmd_on_discovered_dock

      ๐Ÿงช Execute command on a discovered docking station.

      Perform a WebSocket connection test with a discovered docking station. If the dock requires an API token, it must be specified in the request body.
      The IDENTIFY command also blinks the status LED on the dock.

      Response status codes:

      • 200: successful operation: the connection test was successful and docking station metadata could be retrieved.
      • 404: discovered dock with dock_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with DELETE /docks/discover.
      • 503: docking station connection could not be established.
      object allOf
      uid: execCmdOnDiscoveredDockMsg
      • #dock

      Examples

    • #77get_dock_setup_processes

      ๐Ÿงช Get current dock setup processes.

      Return a list of all active setup process identifiers.

      object allOf
      uid: getDockSetupProcessesMsg
      • #dock

      Examples

    • #78create_dock_setup

      ๐Ÿงช Start setting up a new docking station.

      Create a new setup process from a discovered dock or from a manually provided dock address.

      • If there's already a setup process running for the given dock id, status code 409 is returned.
      • Emits the WebSocket event dock_setup_change with event_type: START when this operation returns 201.

      Start setup from dock discovery:

      • The required request data can be obtained from the /api/docks/discover endpoints when searching for docking stations over Bluetooth or Ethernet. Simply provide the returned DockDiscovery data object (which is a super set of the required data to start a setup process).
      • The returned id in the DockSetupInfo response will be the identifier for the next PUT /docks/setup/:id call to provide additional data.

      Manual setup:

      • A dock identifier will automatically be created and returned in DockSetupInfo.
      • The dock must be reachable on the network with the provided custom_ws_url and optional token. Otherwise, status code 503 is returned.
      • The setup process is automatically started after a successful POST request, no call to PUT /docks/setup/:id is required.

      Response status codes:

      • 201: setup process successfully started. Use GET /docks/setup/:id to poll for status updates, or listen to WebSocket dock_setup_change event messages.
      • 400: invalid data in request body.
      • 409: a setup process is already running. Either wait until finished, or abort it.
      • 503: service not available to setup docking station.
        E.g. Bluetooth is disabled and therefore the docking station cannot be setup over Bluetooth. Either enable Bluetooth or setup the dock over Ethernet.
      object allOf
      uid: createDockSetupMsg
      • #dock

      Examples

    • #79stop_all_dock_setups

      ๐Ÿงช Abort and remove all setup processes.

      Stop all setup processes at the next possible operation and remove all setup process information.

      object allOf
      uid: stopAllDockSetupsMsg
      • #dock

      Examples

    • #80get_dock_setup_status

      ๐Ÿงช Get docking station setup status.

      Poll operation to retrieve the current docking station setup state. See the state and error fields in the response message. There are also WebSocket dock_setup_change event messages for state changes to avoid polling.

      Defined setup states:

      • NEW: setup has not yet been started. Use the PUT operation to provide the required data and to start setting up the dock.
      • CONFIGURING: setup data is currently being transferred to the dock.
      • RESTARTING: dock has been configured and is restarting to integrate into the network.
      • OK: setup process has been completed successfully, the dock can now be used.
      • ERROR: the setup process failed. Check the error field for more information.
      object allOf
      uid: getDockSetupStatusMsg
      • #dock

      Examples

    • #81start_dock_setup

      ๐Ÿงช Setup docking station.

      Set required data to start the setup process and configure the docking station. When using Bluetooth the WiFi network name and credentials must be provided to connect the dock to the WiFi network.

      The state field in the response message indicate the current state of the setup process. Use the GET operation to poll for state updates or listen to the corresponding WebSocket dock_setup_change event messages with event_type: SETUP.

      object allOf
      uid: startDockSetupMsg
      • #dock

      Examples

    • #82stop_dock_setup

      ๐Ÿงช Abort the dock setup process.

      Stop the setup process at the next possible operation and remove the setup process information.
      To start a new setup process, use the POST /docks/setup operation again.

      Emits the WebSocket event dock_setup_change with event_type: STOP.

      object allOf
      uid: stopDockSetupMsg
      • #dock

      Examples

    • #83get_wifi_status

      ๐Ÿงช Get WiFi status.

      object allOf
      uid: wifiGetStatusMsg
      • #wifi

      Examples

    • #84wifi_command

      ๐Ÿงช WiFi connection handling.

      Perform one of the following commands on the WLAN interface:

      • DISCONNECT: Disconnect and wait for REASSOCIATE or RECONNECT command before connecting again.
      • RECONNECT: Connect if disconnected (i.e. like REASSOCIATE, but only connect if in disconnected state).
      • REASSOCIATE: Force reassociation.
      • ENABLE_ALL_NETWORKS: Enable all network connections and start connecting to a network if in disconnected state.
      • DISABLE_ALL_NETWORKS: Disable all network connections and disconnect if in connected state.

      โš ๏ธAttention: ENABLE_ALL_NETWORKS and DISABLE_ALL_NETWORKS will persist the state! I.e. if all networks are disabled and the device is restarted afterwards, no WiFi connection will be established.

      object allOf
      uid: wifiCommandMsg
      • #wifi

      Examples

    • #85wifi_scan_start

      ๐Ÿงช Start discovery of WiFi access points.

      Request a new BSS scan. A scan usually takes a few seconds and the current state is returned with the get_wifi_scan_status operation, together with the already found access points.

      object allOf
      uid: wifiScanStartMsg
      • #wifi

      Examples

    • #86wifi_scan_stop

      ๐Ÿงช Stop discovery of WiFi access points.

      Stops the access point discovery. The current discovery status is returned in the response.

      object allOf
      uid: wifiScanStopMsg
      • #wifi

      Examples

    • #87get_wifi_scan_status

      ๐Ÿงช Get discovered WiFi access points.

      Returns the current discovery status and any discovered access points.

      object allOf
      uid: wifiGetScanStatusMsg
      • #wifi

      Examples

    • #88get_all_wifi_networks

      ๐Ÿงช Get configured WiFi networks.

      object allOf
      uid: wifiGetAllNetworksMsg
      • #wifi

      Examples

    • #89add_wifi_network

      ๐Ÿงช Create a new WiFi network configuration.

      Add a new network configuration for the given SSID.
      For an open network without password the password field must be omitted (do not send an empty password value).

      โš ๏ธ Only WPA-PSK (pre shared keys) and open networks are supported!

      object allOf
      uid: wifiAddNetworkMsg
      • #wifi

      Examples

    • #90del_all_wifi_networks

      ๐Ÿงช Delete all configured WiFi networks.

      Disconnects the WiFi network and removes all network configurations.

      โš ๏ธ Attention: the network configuration is automatically persisted and the network configuration cannot be retrieved anymore!

      object allOf
      uid: wifiDelAllNetworksMsg
      • #wifi

      Examples

    • #91get_wifi_network

      ๐Ÿงช Get WiFi network configuration.

      object allOf
      uid: wifiGetNetworkMsg
      • #wifi

      Examples

    • #92update_wifi_network

      ๐Ÿงช Change WiFi network configuration.

      Set a new WiFi network password.

      object allOf
      uid: wifiUpdateNetworkMsg
      • #wifi

      Examples

    • #93wifi_network_command

      ๐ŸงชWiFi network connection handling.

      Perform one of the following commands on a network configuration:

      • ENABLE: Enable a network. If no network is connected, it will be tried to connect to this network.
      • DISABLE: Disable a network. If the network is currently connected it will be disconnected.
      • SELECT: Select the given network and disable all others.

      โš ๏ธ Attention: all network changes (enabled or disabled) are persisted!

      object allOf
      uid: wifiNetworkCommandMsg
      • #wifi

      Examples

    • #94del_wifi_network

      ๐Ÿงช Delete a configured WiFi network.

      The given network is removed from the configuration and disconnected if currently connected.

      โš ๏ธ Attention: the network configuration is automatically persisted and the removed network configuration cannot be retrieved anymore!

      object allOf
      uid: wifiDelNetworkMsg
      • #wifi

      Examples

    • #95bt_pairing_response

      ๐Ÿ” Action to bt_pairing_auth_request event.

      This request needs to be sent for a bt_pairing_auth_request event:

      • Passkey request: either provide the passkey entered by the user, or decline it with confirm: false.
      • NumericComparison request: confirm or decline with confirm: true | false.
      object allOf
      uid: btPairingResponseMsg
      • #event

      Examples

  • SUB /ws

    Core-API for clients to receive messages from the remote.

    Operation IDsubRemoteMessage
    • #core

    Accepts one of the following messages:

    • #0auth_required

      ๐Ÿงช Authentication request event after connection is established.

      This event is only sent if the client didn't provide authentication during connection setup.
      The client must then authenticate with the auth request message.

      object allOf
      uid: authRequiredEvent

      Examples

    • #1authentication

      ๐Ÿงช Authentication response.

      The authentication result is provided in the code attribute:

      • 200: success, API can be used and message requests are accepted.
      • 401: authentication failed, the provided API-key is not valid. The server will close the connection.
      object allOf
      uid: authMsg

      Examples

    • #2pong

      ๐Ÿš€ Pong is a response to ping message

      Server pong response to a ping to determine whether connection is alive. This is an application level pong as opposed to default pong in websockets standard which is sent by client in response to a ping.

      object allOf
      uid: pong

      Examples

    • #3result

      ๐Ÿš€ Command result message

      object
      uid: commonResp

      Common response message properties.

      Examples

    • #4version_info

      ๐Ÿงช Version information response.

      object allOf
      uid: versionInfoMsg

      Examples

    • #5system_info

      ๐Ÿงช System information response.

      object allOf
      uid: systemInfoMsg

      Examples

    • #6factory_reset_token

      Factory reset token response.

      object allOf
      uid: factoryResetTokenMsg

      Examples

    • #7api_access

      API access status response.

      object allOf
      uid: apiAccessMsg

      Examples

    • #8system_update_info

      ๐Ÿงช Available system update response.

      object allOf
      uid: systemUpdateInfoMsg

      Examples

    • #9power_mode

      ๐Ÿงช Current power mode response.

      object allOf
      uid: powerModeMsg

      Examples

    • #10battery_charger

      ๐Ÿ‘ท Battery charger response.

      object allOf
      uid: batteryChargerMsg

      Examples

    • #11ambient_light

      ๐Ÿ” Current ambient light response.

      object allOf
      uid: ambientLightMsg

      Examples

    • #12configuration

      ๐Ÿงช All system settings response.

      object allOf
      uid: configurationMsg

      Examples

    • #13button_cfg

      ๐Ÿงช Button settings response.

      Button backlight configuration.

      Device features:

      • BACKLIGHT: buttons have backlight (UCR2, UCR3).
      • RGB_COLOR: RGB color backlight support (UCR3).
      • ZONES: backlight can be controlled with individual zones (UCR3).

      โš ๏ธ Individual color per zone is not yet supported.

      object allOf
      uid: buttonCfgMsg

      Examples

    • #14device_cfg

      ๐Ÿงช Remote device settings response.

      object allOf
      uid: deviceCfgMsg

      Examples

    • #15display_cfg

      ๐Ÿงช Display settings response.

      object allOf
      uid: displayCfgMsg

      Examples

    • #16haptic_cfg

      ๐Ÿงช Haptic settings response.

      object allOf
      uid: hapticCfgMsg

      Examples

    • #17localization_cfg

      ๐Ÿงช Localization settings response.

      object allOf
      uid: localizationCfgMsg

      Examples

    • #18timezone_names

      ๐Ÿงช Available time zone names response.

      object allOf
      uid: timezoneNamesMsg

      Examples

    • #19localization_countries

      ๐Ÿงช Available localization countries response.

      object allOf
      uid: localizationCountriesMsg

      Examples

    • #20get_localization_languages

      ๐Ÿงช Get stored translations or request available translations from the UI.

      The available translations are provided from the UI application.
      Future UI versions might provide new or updated translations.

      If this request is sent to the UI application, the response is stored in the remote-core until new information is available from the UI.

      If this request is received, the stored configuration from the UI application is returned. E.g. the web-configurator requires the available translations.

      object allOf
      uid: getLocalizationLanguagesMsg

      Examples

    • #21localization_languages

      ๐Ÿงช Available translations response.

      object allOf
      uid: localizationLanguagesMsg

      Examples

    • #22network_cfg

      ๐Ÿ” Network settings response.

      object allOf
      uid: networkCfgMsg

      Examples

    • #23software_update_cfg

      ๐Ÿงช Software update settings response.

      object allOf
      uid: softwareUpdateCfgMsg

      Examples

    • #24power_saving_cfg

      ๐Ÿงช Power saving settings response.

      object allOf
      uid: powerSavingCfgMsg

      Examples

    • #25profile_cfg

      ๐Ÿงช Profile settings response.

      object allOf
      uid: profileCfgMsg

      Examples

    • #26sound_cfg

      ๐Ÿงช Sound settings response.

      object allOf
      uid: soundCfgMsg

      Examples

    • #27voice_control_cfg

      ๐Ÿ” Voice control settings response.

      object allOf
      uid: voiceControlCfgMsg

      Examples

    • #28voice_assistants

      ๐Ÿšง Voice assistants response.

      object allOf
      uid: voiceAssistantsMsg

      Examples

    • #29entity_types

      ๐Ÿงช List of supported entity types response.

      object allOf
      uid: entityTypesMsg
      • #entity

      Examples

    • #30entities

      ๐Ÿงช List of configured entities response.

      object allOf
      uid: entitiesMsg
      • #entity

      Examples

    • #31available_entities

      ๐Ÿงช List of available entities response.

      object allOf
      uid: availableEntitiesMsg
      • #entity

      Examples

    • #32entity_commands

      ๐Ÿงช Available commands of an entity response.

      object allOf
      uid: entityCommandsMsg
      • #entity

      Examples

    • #33entity

      ๐Ÿงช Entity information response.

      object allOf
      uid: entityMsg
      • #entity

      Examples

    • #34dock_count

      ๐Ÿงช Total number of configured docks response.

      object allOf
      uid: dockCountMsg
      • #dock

      Examples

    • #35docks

      ๐Ÿงช Configured docks and their connection state response.

      object allOf
      uid: docksMsg
      • #dock

      Examples

    • #36dock

      ๐Ÿงช Configured dock response.

      object allOf
      uid: dockMsg
      • #dock

      Examples

    • #37dock_discovery_status

      ๐Ÿงช Docking station discovery status response.

      object allOf
      uid: dockDiscoveryStatusMsg
      • #dock

      Examples

    • #38dock_discovery_device

      ๐Ÿงช Docking station discovery device status response.

      object allOf
      uid: dockDiscoveryDeviceMsg
      • #dock

      Examples

    • #39dock_system_info

      ๐Ÿงช Dock system information response.

      object allOf
      uid: dockSystemInfoMsg
      • #dock

      Examples

    • #40dock_setup_processes

      ๐Ÿงช Current dock setup processes response.

      object allOf
      uid: dockSetupProcessesMsg
      • #dock

      Examples

    • #41dock_setup_status

      ๐Ÿงช Dock setup information response.

      object allOf
      uid: dockSetupStatusMsg
      • #dock

      Examples

    • #42wifi_status

      ๐Ÿงช WiFi status.

      object allOf
      uid: wifiStatusMsg
      • #wifi

      Examples

    • #43wifi_scan_status

      ๐Ÿงช Discovered WiFi access points.

      object allOf
      uid: wifiScanStatusMsg
      • #wifi

      Examples

    • #44wifi_networks

      ๐Ÿงช Configured WiFi networks.

      object allOf
      uid: wifiNetworksMsg
      • #wifi

      Examples

    • #45wifi_network

      ๐Ÿงช WiFi network configuration.

      object allOf
      uid: wifiNetworkMsg
      • #wifi

      Examples

    • #46bt_pairing_started

      ๐Ÿ” Inform user that pairing has started.

      Emitted if a central started pairing with the Remote.

      object allOf
      uid: btPairingStartedEventMsg
      • #event

      Examples

    • #47bt_pairing_auth_request

      ๐Ÿ” Request pairing authorization from the user.

      Depending on authentication requirements, IO capabilities, etc. a different type of authentication is requested. The client must respond with the bt_pairing_response event.

      object allOf
      uid: btPairingAuthRequestEventMsg
      • #event

      Examples

    • #48bt_pairing_complete

      ๐Ÿ” Bonding process has finished.

      This event is emitted after the bonding process, either with a success state or an error code if bonding failed.

      object allOf
      uid: btPairingCompleteEventMsg
      • #event

      Examples

  • PUB /intg

    Integration driver and instance management.

    โš ๏ธ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all integration driver and instance related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDpubIntegrationMessage
    • #integrations

    Accepts one of the following messages:

    • #0get_integration_status

      ๐Ÿงช Retrieve an overview of the integration instances and their current connection state.

      object allOf
      uid: getIntegrationStatusMsg
      • #integration

      Examples

    • #1integration_cmd

      ๐Ÿงช Execute an integration command.

      Connect or disconnect integration instances.

      If integration_id is specified, then the command only applies to the given integration, otherwise to all integration instances.

      object allOf
      uid: integrationCmdMsg
      • #integration

      Examples

    • #2integration_driver_cmd

      ๐Ÿงช Execute an integration driver command.

      Start or stop integration drivers.

      If driver_id is specified, then the command only applies to the given driver, otherwise to all integration drivers.

      object allOf
      uid: integrationDriverCmdMsg
      • #integration

      Examples

    • #3get_integration_driver_count

      ๐Ÿงช Get total number of registered integration drivers.

      object allOf
      uid: getIntegrationDriverCountMsg
      • #integration

      Examples

    • #4get_integration_drivers

      ๐Ÿงช Retrieve all registered integration drivers.

      object allOf
      uid: getIntegrationDriversMsg
      • #integration

      Examples

    • #5register_integration_driver

      ๐Ÿงช Register a new integration driver.

      object allOf
      uid: registerIntegrationDriverMsg
      • #integration

      Examples

    • #6get_integration_driver

      ๐Ÿงช Retrieve detail information of an integration driver.

      object allOf
      uid: getIntegrationDriverMsg
      • #integration

      Examples

    • #7update_integration_driver

      ๐Ÿงช Modify a configured integration driver.

      object allOf
      uid: updateIntegrationDriverMsg
      • #integration

      Examples

    • #8delete_integration_driver

      ๐Ÿงช Remove an integration driver.

      Unloads and deletes an integration driver with all instances and provided entities.

      Attention: all references to the integration driver will be removed! This includes all driver instances, provided entities and their references in profile pages and groups.

      object allOf
      uid: deleteIntegrationDriverMsg
      • #integration

      Examples

    • #9get_integration_count

      ๐Ÿงช Get total number of integration instances.

      object allOf
      uid: getIntegrationCountMsg
      • #integration

      Examples

    • #10get_integrations

      ๐Ÿงช Retrieve all loaded integrations.

      Returns all integration instances, optionally filtered by type or enabled state.

      object allOf
      uid: getIntegrationsMsg
      • #integration

      Examples

    • #11create_integration

      ๐Ÿงช Create a new integration instance from driver.

      Create an integration driver instance and associate it with the driver. For simple integration drivers there's a 1:1 relationship only between an instance and driver. For multi-device drivers, each device corresponds to an integration instance.

      • the integration_id is automatically created by the system to make it unique over all integrations.
      • for multi-device drivers the device_id must be specified and may not already exist in another instance of the same driver.
      • the driver's name is used by default if name isn't specified.
      • the instance is active by default if enabled isn't specified.
      object allOf
      uid: createIntegrationMsg
      • #integration

      Examples

    • #12get_integration

      ๐Ÿงช Get an integration instance.

      object allOf
      uid: getIntegrationMsg
      • #integration

      Examples

    • #13update_integration

      ๐Ÿงช Modify a configured integration instance.

      Modify one or several properties of an integration instance.
      See update model description on how to update or delete an existing property.

      The integration driver of an instance cannot be changed and will be ignored if provided in the request.

      object allOf
      uid: updateIntegrationMsg
      • #integration

      Examples

    • #14delete_integration

      ๐Ÿงช Remove an integration instance.

      Unloads and deletes an integration instance.

      Attention: all references to the integration instance will be removed! This includes configured entities and their references in profile pages and groups.

      object allOf
      uid: deleteIntegrationMsg
      • #integration

      Examples

    • #15configure_entity_from_integration

      ๐Ÿงช Configure an available entity.

      Configure a new UC Remote entity from an available integration entity. Once configured, the entity will no longer show up as available entity (unless the all filter is set).

      The entity name, icon and description fields may be changed. If not specified in the request the values from the available entity are used.

      In case of an error the default result message is returned with an error code.

      object allOf
      uid: configureEntityFromIntegrationMsg
      • #integration

      Examples

    • #16configure_entities_from_integration

      ๐Ÿงช Configure multiple available entities.

      Configure multiple new UC Remote entities from available integration entities. Once configured, the entities will no longer show up as an available entity (unless the filter=ALL query parameter is set).

      If entity_ids is not provided or is empty, all entities from the integration are configured.

      Use message configure_entity_from_integration to configure a single entity and optionally rename it or change its icon.

      This is a best effort operation:

      • if an entity is already configured, it is ignored and not returned in the response.
      • unknown entity identifiers are ignored, no error is returned.

      Every newly configured entity will trigger an entity_change event.

      object allOf
      uid: configureEntitiesFromIntegrationMsg
      • #integration

      Examples

    • #17get_integration_discovery_status

      ๐Ÿงช Get external integration driver discovery status.

      Returns the current discovery status and the discovered integration drivers.

      Use start_integration_discovery to clear old results and start a new discovery.

      object allOf
      uid: getIntegrationDiscoveryStatusMsg
      • #integration

      Examples

    • #18start_integration_discovery

      ๐Ÿงช Start discovery of external integration drivers.

      Start integration driver discovery on the network with mDNS. By default the discovery automatically stops after 30 seconds. Use the get_integration_discovery_status request to check on discovered devices or stop_integration_discovery to stop discovery.

      By default only new integration drivers are returned. If a driver is already configured it will be omitted from the results, unless the query parameter new=false is set.

      • Previously discovered integrations are removed, only newly discovered integrations will be returned.
      • Emits the WebSocket event integration_discovery with event_type: START when discovery starts.
      • For each discovered driver the WebSocket event integration_discovery with event_type: DISCOVER is emitted.
      object allOf
      uid: startIntegrationDiscoveryMsg
      • #integration

      Examples

    • #19stop_integration_discovery

      ๐Ÿงช Stop discovery of external integration drivers.

      Stops the driver discovery and returns the current discovery status in the response.

      Emits the WebSocket event integration_discovery with event_type: STOP.

      object allOf
      uid: stopIntegrationDiscoveryMsg
      • #integration

      Examples

    • #20get_discovered_integration_driver

      ๐Ÿงช Get integration driver discovery information.

      Returns the discovered integration driver.

      object allOf
      uid: getDiscoveredIntegrationDriverMsg
      • #integration

      Examples

    • #21get_discovered_intg_driver_metadata

      ๐Ÿ‘ท Execute connection test and fetch metadata from discovered integration driver.

      Perform a driver connection test with a discovered driver. If the driver requires a token, it must be specified in the request data.

      Response status codes:

      • 200: successful operation: the connection test was successful and driver metadata could be retrieved.
      • 404: discovered driver with driver_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with starting a new discovery.
      • 503: integration driver connection could not be established.
      object allOf
      uid: getDiscoveredIntgDriverMetadataMsg
      • #integration

      Examples

    • #22configure_discovered_integration_driver

      ๐Ÿงช Register a discovered integration driver.

      Register a discovered integration driver:

      • establish communication with the driver.
        • if the driver requires a password, it must be provided in the request.
        • the discovered driver name and url can be overridden.
      • fetch metadata from the driver.
      • check compatability.
      • register the driver and connection parameters in the remote.

      After a successful registration the setup process of the driver can be started to configure the integration. The required setup data is described in the returned setup_data_schema and the provided values by the user must be passed to the setup_integration request.

      Response status codes:

      • 400: invalid data in request body.
      • 404: no discovered driver found for given driver_id.
      • 409: integration driver is already registered.
      • 503: integration driver communication error. Either driver is not reachable or communication failed.
      object allOf
      uid: configureDiscoveredIntegrationDriverMsg
      • #integration

      Examples

    • #23get_integration_setup_processes

      ๐Ÿงช Get current integration setup processes.

      Return a list of all active setup process identifiers. The returned ids can be used with the set_integration_user_data and stop_integration_setup messages to continue or abort a setup process.

      object allOf
      uid: getIntegrationSetupProcessesMsg
      • #integration

      Examples

    • #24setup_integration

      ๐Ÿงช Start setting up a new integration driver.

      Start a new setup process for the given integration driver and provided setup data, or reconfigure an existing driver.

      • This operation immediately starts the driver communication and setup process.
      • There may only be one active setup process per driver, otherwise status code 409 is returned.

      The returned id in the IntegrationSetupInfo response will be the identifier for the further setup operations with the set_integration_user_data and stop_integration_setup requests. Once the setup process is successfully finished, an integration instance is created. A setup process can be simple and fully automatic, but may also require user interaction and further communication with the set_integration_user_data message.

      Emits the WebSocket event integration_setup_change with event_type: START.

      Request body:

      • name: optional integration name. If not specified the name of the integration driver is used.
      • setup_data: optional driver setting values corresponding to the driver's setup_data_schema object.
      • reconfigure: set to true to reconfigure an already configured driver. The configuration options and behaviour is driver dependent.

      Response status codes:

      • 400: invalid data in request body. E.g. setting the reconfigure flag for a new driver which is not yet configured.
      • 404: specified driver_id in request body does not exist.
      • 409: a setup process for the given driver_id already exists. Either continue or abort existing process.
      • 422: the setup process cannot be used: either the integration is already configured or doesn't allow to be set up again.
      • 503: integration driver communication error. Either driver is not reachable or communication failed.
      object allOf
      uid: setupIntegrationMsg
      • #integration

      Examples

    • #25stop_all_integration_setups

      ๐Ÿงช Abort and remove all setup processes.

      Stop all setup processes at the next possible operation and remove all setup process information.
      Depending on the integration driver, a started setup process cannot be aborted.

      โš ๏ธ This stops all setup processes, not just for the current session!

      object allOf
      uid: stopAllIntegrationSetupsMsg
      • #integration

      Examples

    • #26get_integration_setup_status

      ๐Ÿงช Get integration driver setup status.

      Poll operation to retrieve the current integration driver setup state. See the state and error fields in the response message. There are also WebSocket integration_setup_change event messages for state changes to avoid polling.

      Defined setup states:

      • SETUP: setup is running and configuring the integration.
      • WAIT_USER_ACTION: user input is required to continue the setup process. See require_user_action in response for the required user input. Provide the requested data with the PUT operation.
      • OK: setup process has been completed successfully, the integration driver can now be used.
      • ERROR: the setup process failed. Check the error field for more information.
      object allOf
      uid: getIntegrationSetupStatusMsg
      • #integration

      Examples

    • #27set_integration_user_data

      ๐Ÿงช Provide requested integration setup data.

      Set required data to configure the integration driver or continue the setup process.

      Defined user actions to set in the request body action field:

      • input_values: if the user was requested to enter settings, e.g. connection or credential parameters to a device or service.
      • confirm: response to the user action confirmation. Set to true if the user had to perform an action like pressing a button on a device and then confirms the action with continuing the setup process.
        The false value is prepared for yes / no choices.

      The state field in the response message indicate the current state of the setup process. Use the get_integration_setup_status message to poll for state updates or listen to the corresponding WebSocket integration_setup_change event messages with event_type: SETUP.

      object allOf
      uid: setIntegrationUserDataMsg
      • #integration

      Examples

    • #28stop_integration_setup

      ๐Ÿงช Abort the integration driver setup process.

      Stop the setup process at the next possible operation and remove the setup process information.
      To start a new setup process, use the setup_integration request again.

      Depending on the integration driver, a started setup process cannot be aborted.

      Emits the WebSocket event integration_setup_change with event_type: STOP.

      object allOf
      uid: stopIntegrationSetupMsg
      • #integration

      Examples

  • SUB /intg

    โš ๏ธ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all integration driver and instance related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDsubIntegrationMessage
    • #integrations

    Accepts one of the following messages:

    • #0integration_status

      ๐Ÿงช Summary information of the integration instances.

      object allOf
      uid: integrationStatusMsg
      • #integration

      Examples

    • #1integration_driver_count

      ๐Ÿงช Total number of registered integration drivers response.

      object allOf
      uid: integrationDriverCountMsg
      • #integration

      Examples

    • #2integration_drivers

      ๐Ÿงช List of registered integration drivers response.

      object allOf
      uid: integrationDriversMsg
      • #integration

      Examples

    • #3integration_driver

      ๐Ÿงช Detail information of an integration driver response.

      object allOf
      uid: integrationDriverMsg
      • #integration

      Examples

    • #4integration_count

      ๐Ÿงช Total number of integration instances response.

      object allOf
      uid: integrationCountMsg
      • #integration

      Examples

    • #5integrations

      ๐Ÿงช List of loaded integrations response.

      object allOf
      uid: integrationsMsg
      • #integration

      Examples

    • #6integration

      ๐Ÿงช Integration instance information response.

      object allOf
      uid: integrationMsg
      • #integration

      Examples

    • #7integration_discovery_status

      ๐Ÿงช External integration driver discovery status response.

      object allOf
      uid: integrationDiscoveryStatusMsg
      • #integration

      Examples

    • #8discovered_integration_driver

      ๐Ÿงช Integration driver discovery information.

      object allOf
      uid: discoveredIntegrationDriverMsg
      • #integration

      Examples

    • #9integration_setup_processes

      ๐Ÿงช Current integration setup processes response.

      Return a list of all active setup process identifiers.

      object allOf
      uid: integrationSetupProcessesMsg
      • #integration

      Examples

    • #10integration_setup_info

      ๐Ÿงช Integration setup information response.

      object allOf
      uid: integrationSetupInfoMsg
      • #integration

      Examples

  • PUB /profiles

    Profile management.

    โš ๏ธ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all profile related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDpubProfileMessage
    • #profiles

    Accepts one of the following messages:

    • #0get_profiles

      ๐Ÿงช Retrieve all profiles.

      object allOf
      uid: getProfilesMsg
      • #profile

      Examples

    • #1get_profile

      ๐Ÿงช Retrieve the specified profile.

      object allOf
      uid: getProfileMsg
      • #profile

      Examples

    • #2get_active_profile

      ๐Ÿงช Retrieve the active profile.

      If no profile exists, or no profile is set active, 404 is returned.

      object allOf
      uid: getActiveProfileMsg
      • #profile

      Examples

    • #3switch_profile

      ๐Ÿงช Switch active profile.

      The administrator PIN in admin_pin is required to switch from a restricted to a normal profile. If the current profile is a restricted profile and the pin is missing, error 401 is returned.

      object allOf
      uid: switchProfileMsg
      • #profile

      Examples

    • #4add_profile

      ๐Ÿงช Add a new profile.

      There are two different types of profiles:

      • Normal profile (default): can do anything, change settings, add pages, entities, integrations, etc.
      • Restricted profile: intended for guests or children, who can only use the remote, but cannot change settings.

      The admin PIN is required to switch from a restricted to a normal profile. It can be defined in settings.

      • Switching away from a restricted profile will prompt the user to enter the admin PIN.
      • Switching to a restricted profile can be done without entering the admin PIN.

      Profile request object:

      • profile_id is optional and auto-generated if not specified. Otherwise it needs to be a unique profile identifier.
      • name is mandatory and must be unique.
      • if the first profile is added, it is automatically set as the active profile.
      object allOf
      uid: addProfileMsg
      • #profile

      Examples

    • #5update_profile

      ๐Ÿงช Update a profile.

      Update one or multiple properties of a profile. A missing property will not update its current value.

      • profile_id is mandatory and can't be changed.
      • an empty icon value removes an existing icon identifier.
      • a missing pages property will not change the page order.
      • โš ๏ธ an empty pages array removes all pages and groups in the profile!
      • โš ๏ธ missing page identifiers in the pages array will remove the page configuration!
      object allOf
      uid: updateProfileMsg
      • #profile

      Examples

    • #6delete_profile

      ๐Ÿงช Delete the specified profile.

      All profile related pages and groups are also deleted.

      object allOf
      uid: deleteProfileMsg
      • #profile

      Examples

    • #7delete_all_profiles

      ๐Ÿงช Delete all profiles.

      This also deletes all pages and groups.

      object allOf
      uid: deleteAllProfilesMsg
      • #profile

      Examples

    • #8get_pages

      ๐Ÿงช Retrieve all UI pages of a profile.

      object allOf
      uid: getPagesMsg
      • #profile

      Examples

    • #9get_page

      ๐Ÿงช Retrieve the specified UI page.

      object allOf
      uid: getPageMsg
      • #profile

      Examples

    • #10add_page

      ๐Ÿงช Create a new UI page and add to profile.

      • profile_id is mandatory.
      • page_id is not required and is created automatically.
      • name is mandatory and must be unique within the profile.
      object allOf
      uid: addPageMsg
      • #profile

      Examples

    • #11update_page

      ๐Ÿงช Update a UI page.

      • profile_id and page_id are mandatory.
      object allOf
      uid: updatePageMsg
      • #profile

      Examples

    • #12delete_page

      ๐Ÿงช Delete a UI page.

      object allOf
      uid: deletePageMsg
      • #profile

      Examples

    • #13delete_pages_in_profile

      ๐Ÿงช Delete all pages of a profile

      object allOf
      uid: deletePagesInProfileMsg
      • #profile

      Examples

    • #14get_groups

      ๐Ÿงช Retrieve all UI groups of a profile.

      object allOf
      uid: getGroupsMsg
      • #profile

      Examples

    • #15get_group

      ๐Ÿงช Retrieve the specified UI group.

      object allOf
      uid: getGroupMsg
      • #profile

      Examples

    • #16add_group

      ๐Ÿงช Create a new UI group and add to profile.

      • profile_id is mandatory.
      • group_id is not required and is created automatically.
      • name is mandatory and must be unique within the profile.
      object allOf
      uid: addGroupMsg
      • #profile

      Examples

    • #17update_group

      ๐Ÿงช Update a UI group.

      • profile_id and group_id are mandatory.
      object allOf
      uid: updateGroupMsg
      • #profile

      Examples

    • #18delete_group

      ๐Ÿงช Delete a UI group.

      object allOf
      uid: deleteGroupMsg
      • #profile

      Examples

    • #19delete_groups_in_profile

      ๐Ÿงช Delete all groups in a profile.

      object allOf
      uid: deleteGroupsInProfileMsg
      • #profile

      Examples

  • SUB /profiles

    โš ๏ธ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all profile related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDsubProfileMessage
    • #profiles

    Accepts one of the following messages:

    • #0profile

      ๐Ÿงช Profile data response.

      object allOf
      uid: profileMsg
      • #profile

      Examples

    • #1profiles

      ๐Ÿงช List of available profiles response.

      object allOf
      uid: profilesMsg
      • #profile

      Examples

    • #2page

      ๐Ÿงช UI page data response.

      object allOf
      uid: pageMsg
      • #profile

      Examples

    • #3pages

      ๐Ÿงช List of defined UI pages response.

      object allOf
      uid: pagesMsg
      • #profile

      Examples

    • #4group

      ๐Ÿงช UI group data response.

      object allOf
      uid: groupMsg
      • #profile

      Examples

    • #5groups

      ๐Ÿงช List of defined UI groups response.

      object allOf
      uid: groupsMsg
      • #profile

      Examples

  • PUB /events

    Notification signup for the client to receive event messages.

    โš ๏ธ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of event messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDpubEventMessage
    • #events

    Accepts one of the following messages:

    • #0get_event_channels

      ๐Ÿงช Retrieve available event channels for the current session.

      Depending on the security role not all event subscriptions may be available.

      object allOf
      uid: getEventChannelsMsg
      • #event

      Examples

    • #1subscribe_events

      ๐Ÿงช Subscribe to event channels.

      Subscribe to one or multiple event channels.

      • The special all channel will deliver all available events and clear all other subscriptions for the session.
      • If the session is already subscribed to the all channel, any other channels are ignored.
      • The special entities channel will deliver all entity and activity-group related events. This includes all entity-type channels (entity_###) and the activity_group channel.
      • Depending on the security role not all event subscriptions may be available.
      object allOf
      uid: subscribeEventsMsg
      • #event

      Examples

    • #2get_event_subscriptions

      ๐Ÿงช Retrieve the active event channel subscriptions.

      object allOf
      uid: getEventSubscriptionsMsg
      • #event

      Examples

    • #3unsubscribe_events

      ๐Ÿงช Unsubscribe from event channels.

      object allOf
      uid: unsubscribeEventsMsg
      • #event

      Examples

  • SUB /events

    Event messages for signed up channels.

    โš ๏ธ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of event messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDsubEventMessage
    • #events

    Accepts one of the following messages:

    • #0event_channels

      ๐Ÿงช Available subscriptions for the current session.

      Returns all subscribed event channels.

      object allOf
      uid: eventChannelsMsg
      • #event

      Examples

    • #1event_subscriptions

      ๐Ÿงช Event channel subscription status.

      Response to subscribe_events, unsubscribe_events and get_event_subscriptions.

      object allOf
      uid: eventSubscriptionsMsg
      • #event

      Examples

    • #2warning

      ๐Ÿ” System warning event.

      Emitted for important system events like low battery or shutdown events.

      object allOf
      uid: warningEventMsg
      • #event

      Examples

    • #3entity_change

      ๐Ÿงช Entity change event.

      Emitted if an entity has changed, a new entity has been added or a configured entity has been deleted.

      If an entity state or dynamic attribute has changed (through notification of an integration driver), then only the attributes object is included within new_state. This happens after an entity_command or if the entity is updated manually through a user or an external system, e.g. if it has been switched off.

      If the entity definition has changed, e.g. the name, description or icon has been modified with the web configurator, the full entity data is included within new_state.

      If a complete integration is removed then only an integration_change event is sent, i.e. there won't be individual entity_change events for every removed entity!

      โš ๏ธ This event is also used to indicate the client to reload all entities. This is the case if only event_type: change is set and the entity_id field is missing.

      object allOf
      uid: entityChangeEventMsg
      • #entity
      • #event

      Examples

    • #4activity_group_change

      ๐Ÿงช Activity group change event.

      Emitted if an activity group has changed, a new group has been added or a group has been deleted.

      โš ๏ธ This event is also used to indicate the client to reload all activity groups. This is the case if only event_type: change is set and the group_id field is missing.

      object allOf
      uid: activityGroupChangeEventMsg
      • #entity
      • #event

      Examples

    • #5wifi_change

      ๐Ÿงช WiFi change event.

      Emitted if the WiFi status changed, e.g. connected or disconnected to an access point, or if a WiFi network scan finished.

      object allOf
      uid: wifiChangeEventMsg
      • #event

      Examples

    • #6integration_driver_change

      ๐Ÿงช Integration driver change event.

      Emitted if an integration driver has changed, a new driver has been added or a configured driver has been deleted.

      object allOf
      uid: integrationDriverChangeEventMsg
      • #integration
      • #event

      Examples

    • #7integration_change

      ๐Ÿงช Integration change event.

      Emitted if an integration instance has changed, a new instance has been added or a configured instance has been deleted.

      object allOf
      uid: integrationChangeEventMsg
      • #integration
      • #event

      Examples

    • #8integration_state

      ๐Ÿงช Integration state event.

      Emitted if the connection state of an integration driver or instance has changed.

      object allOf
      uid: integrationStateEventMsg
      • #integration
      • #event

      Examples

    • #9active_profile_change

      ๐Ÿงช Active profile change event.

      Emitted if the active profile changed.

      object allOf
      uid: activeProfileChangeEventMsg
      • #profile
      • #event

      Examples

    • #10profile_change

      ๐Ÿงช Profile change event.

      Emitted if a profile configuration, related profile page or group has been changed, added or deleted.

      object allOf
      uid: profileChangeEventMsg
      • #profile
      • #event

      Examples

    • #11configuration_change

      ๐Ÿงช System configuration change event.

      Emitted if a system setting has changed.

      The msg_data.new_state object only contains the configuration object of the setting that has changed and not the full system configuration.

      object allOf
      uid: configurationChangeEventMsg
      • #event

      Examples

    • #12ir_learning

      ๐Ÿงช IR code learn event.

      Emitted if learning mode is started, stopped or a new IR code was learned from an IR emitter device.

      object allOf
      uid: irLearningEventMsg
      • #event

      Examples

    • #13dock_change

      ๐Ÿงช Dock change event.

      Emitted if a dock configuration has changed.

      object allOf
      uid: dockChangeEventMsg
      • #event

      Examples

    • #14dock_state

      ๐Ÿงช Dock state event.

      Emitted if the connection state of a dock has changed.

      object allOf
      uid: dockStateEventMsg
      • #event

      Examples

    • #15dock_discovery

      ๐Ÿงช Docking station discovery event.

      Emitted if dock discovery is started, stopped or a new dock was discovered on the network or via Bluetooth.

      object allOf
      uid: dockDiscoveryEventMsg
      • #event

      Examples

    • #16dock_setup_change

      ๐Ÿงช Docking station setup state change event.

      Emitted for all dock setup flow state changes.

      object allOf
      uid: dockSetupChangeEventMsg
      • #event

      Examples

    • #17dock_update_change

      ๐Ÿงช Docking station firmware update change event.

      Emitted for firmware update and progress state changes.

      object allOf
      uid: dockUpdateChangeEventMsg
      • #event

      Examples

    • #18integration_discovery

      ๐Ÿงช Integration discovery event.

      Emitted if integration discovery is started, stopped or a new integration was discovered on the network.

      object allOf
      uid: integrationDiscoveryEventMsg
      • #event

      Examples

    • #19integration_setup_change

      ๐Ÿงช Integration setup state change event.

      Emitted for all integration setup flow state changes.

      object allOf
      uid: integrationSetupChangeEventMsg
      • #event

      Examples

    • #20software_update

      ๐Ÿงช Software update event.

      Emitted during a system update to receive start, stop and progress events.

      object allOf
      uid: softwareUpdateEventMsg
      • #event

      Examples

    • #21power_mode_change

      ๐Ÿงช Power mode change event.

      Emitted when the power saving mode changes.

      object allOf
      uid: powerModeChangeEventMsg
      • #event

      Examples

    • #22battery_status

      ๐Ÿงช Battery status event.

      Emitted when the battery status changes.

      object allOf
      uid: batteryStatusEventMsg
      • #event

      Examples

    • #23ambient_light_change

      ๐Ÿ” Ambient light change event.

      Emitted when the ambient light changes during normal power mode.

      object allOf
      uid: ambientLightChangeEventMsg
      • #event

      Examples

Messages

  • #1request

    ๐Ÿš€ Generic request message.

    object
    uid: commonReq

    Common request message properties.

  • #2response

    ๐Ÿš€ Generic response message.

    object
    uid: commonResp

    Common response message properties.

  • #3event

    ๐Ÿš€ Generic event message of a subscribed channel.

    object
    uid: commonEvent

    Common event message properties.

  • #4auth_required

    ๐Ÿงช Authentication request event after connection is established.

    This event is only sent if the client didn't provide authentication during connection setup.
    The client must then authenticate with the auth request message.

    object allOf
    uid: authRequiredEvent
  • #5auth

    ๐Ÿงช Authenticate a connection.

    Sent by the client right after establishing a connection if header authentication cannot be used, or after an auth_required request by the server.

    object allOf
    uid: authRequestMsg
  • #6authentication

    ๐Ÿงช Authentication response.

    The authentication result is provided in the code attribute:

    • 200: success, API can be used and message requests are accepted.
    • 401: authentication failed, the provided API-key is not valid. The server will close the connection.
    object allOf
    uid: authMsg
  • #7ping

    ๐Ÿš€ Application level based ping to determine whether connection is alive.

    Client can ping the server to determine whether connection is alive. Server responds with pong.

    This is an application level ping as opposed to the standard WebSocket ping frames. This is only required if a client framework doesn't support WebSocket ping frames!
    Additional payload data may be included in msg_data which will be echoed by the server. E.g. a client timestamp to calculate round trip times.

    object allOf
    uid: ping
  • #8pong

    ๐Ÿš€ Pong is a response to ping message

    Server pong response to a ping to determine whether connection is alive. This is an application level pong as opposed to default pong in websockets standard which is sent by client in response to a ping.

    object allOf
    uid: pong
  • #9result

    ๐Ÿš€ Command result message

    object
    uid: commonResp

    Common response message properties.

  • #10version

    ๐Ÿš€ Get version information.

    object allOf
    uid: versionMsg
  • #11version_info

    ๐Ÿงช Version information response.

    object allOf
    uid: versionInfoMsg
  • #12system

    ๐Ÿš€ Get system information.

    Get hardware information about the device like serial number, model number and hardware revision.

    object allOf
    uid: getSystemInfoMsg
  • #13system_info

    ๐Ÿงช System information response.

    object allOf
    uid: systemInfoMsg
  • #14system_cmd

    ๐Ÿงช Perform a system command like reboot or power-off.

    The following system commands can be executed:

    • STANDBY: Put the device into standby mode.
    • REBOOT: Reboot the device.
    • POWER_OFF: Switch off the device
    • RESTART: Restart all applications.
    • RESTART_UI: Restart the ui application.
    • RESTART_CORE: Restart the core service application.

    The server will respond with a result message and a status code of the request.
    For status code 200 the WebSocket connection will be closed and the command executed.

    object allOf
    uid: systemCmdMsg
  • #15get_factory_reset_token

    Get factory reset token.

    Get a factory reset token to perform a complete factory reset of the remote.

    The token will be valid for 60 seconds. Afterwards, a new token must be requested.
    Whenever a new token is requested, any old tokens will be invalidated.

    object allOf
    uid: getFactoryResetTokenMsg
  • #16factory_reset_token

    Factory reset token response.

    object allOf
    uid: factoryResetTokenMsg
  • #17factory_reset

    Perform a factory reset.

    A factory reset removes all configuration data and puts the device into a clean state.

    โš ๏ธ Warning: All user data will be erased and won't be recoverable!

    A reset token must be requested first and provided to perform a factory reset.

    object allOf
    uid: factoryResetMsg
  • #18set_api_access

    Enable or disable API access.

    Enable / disable API access for web-configurator. If the account gets disabled, all active sessions are closed and WebSocket connections disconnected.
    The server will respond with a result message and a status code of the request.

    object allOf
    uid: setApiAccessMsg
  • #19get_api_access

    Get API access status.

    The server will respond with an api_access message.

    object allOf
    uid: getApiAccessMsg
  • #20api_access

    API access status response.

    object allOf
    uid: apiAccessMsg
  • #21check_system_update

    ๐Ÿงช Check if system update is available.

    Returns the known available system updates.

    System update checks are run automatically (if not disabled in settings). Use the force_update flag to force an update check.

    object allOf
    uid: checkSystemUpdateMsg
  • #22system_update_info

    ๐Ÿงช Available system update response.

    object allOf
    uid: systemUpdateInfoMsg
  • #23update_system

    ๐Ÿงช Perform system update.

    Start a system update with the given update_id parameter. Use latest to use the latest available system update.

    The system update will be started if:

    • the system update has been downloaded already (download state is DOWNLOADED).
    • the device has at least 50% battery charge.

    If the system update is started, the response message contains state: START. In case there's not enough battery, 503 service unavailable is returned. It is recommended to perform the update while the remote is charging in the docking station.

    The progress of the system update can be retrieved with the get_system_update_progress message, or by listening to the software_update event messages.

    If the system update hasn't been downloaded yet (download state is PENDING or ERROR), this operation will only start the download and return state: DOWNLOAD. Once successfully downloaded, it can be installed by this request message again.

    The download process emits software_update progress event messages with event_type: PROGRESS and state: DOWNLOAD. The payload fields download_bytes, download_percent and update_id are set.

    • A successful download is indicated with download_percent: 100, without the download_bytes field.
    • The state is set to FAILURE if a download fails.
    • Depending on download speed, download_percent might skip certain values or report the same value multiple times.
    • The famous last percent will take longer due to image validation.

    Example download progress events:

    • Download progress event:
    {
      "kind": "event",
      "msg": "software_update",
      "cat": "REMOTE",
      "ts": "2024-09-30T16:25:18.668395688Z",
      "msg_data": {
        "event_type": "PROGRESS",
        "progress": {
          "download_bytes": 256734720,
          "download_percent": 97,
          "state": "DOWNLOAD",
          "update_id": "some-id"
        },
        "update_id": "some-id"
      }
    }
    
    • Final success event:
    {
      "kind": "event",
      "msg": "software_update",
      "cat": "REMOTE",
      "ts": "2024-09-30T16:25:34.229442566Z",
      "msg_data": {
        "event_type": "PROGRESS",
        "progress": {
          "download_percent": 100,
          "state": "DOWNLOAD",
          "update_id": "some-id"
        },
        "update_id": "some-id"
      }
    }
    
    object allOf
    uid: updateSystemMsg
  • #24update_system_result

    ๐Ÿงช System update response.

    Returns the state of the system update request.

    object allOf
    uid: updateSystemResultMsg
  • #25get_system_update_progress

    ๐Ÿงช Get system update progress.

    This is a manual request for the update progress if the system update event messages cannot be used.

    object allOf
    uid: getSystemUpdateProgressMsg
  • #26system_update_progress

    ๐Ÿงช System update progress response.

    object allOf
    uid: systemUpdateProgressMsg
  • #27get_power_mode

    ๐Ÿงช Get current power mode and battery information.

    object allOf
    uid: getPowerModeMsg
  • #28power_mode

    ๐Ÿงช Current power mode response.

    object allOf
    uid: powerModeMsg
  • #29set_power_mode

    ๐Ÿงช Change the current power mode.

    object allOf
    uid: setPowerModeMsg
  • #30get_battery_charger

    ๐Ÿ‘ท Get battery charger information.

    Device features:

    • DOCK_CHARGING: device can be charged in docking station (UCR2, UCR3).
    • WIRELESS_CHARGING: device has wireless charging support (UCR3).
    object allOf
    uid: getBatteryChargerMsg
  • #31battery_charger

    ๐Ÿ‘ท Battery charger response.

    object allOf
    uid: batteryChargerMsg
  • #32update_battery_charger

    ๐Ÿ‘ท Enable or disable wireless charging.

    object allOf
    uid: updateBatteryChargerMsg
  • #33get_standby_inhibitors

    ๐Ÿงช Get standby inhibitors.

    Automatic system standby can be prevented with "standby inhibitors". For example during integration setup or as a user option for activities.

    There are two types of inhibitors:

    • Temporary inhibitors set a delay value for which the device doesn't go into standby. After the delay and the idle timeouts have expired, the remote goes into standby and the temporary inhibitor will be removed.
    • Blocking inhibitors will prevent the device to go into standby until the inhibitor is removed by the client.

    Note: temporary inhibitors will only be checked and removed during standby events. As long as the device is active, they may still appear in the result.

    object allOf
    uid: getStandbyInhibitorsMsg
  • #34standby_inhibitors

    ๐Ÿงช Standby inhibitors response.

    object allOf
    uid: inhibitorsMsg
  • #35create_standby_inhibitor

    ๐Ÿงช Create a standby inhibitor.

    object allOf
    uid: createStandbyInhibitorMsg
  • #36standby_inhibitor

    ๐Ÿงช Standby inhibitor response.

    object allOf
    uid: inhibitorMsg
  • #37del_standby_inhibitor

    ๐Ÿงช Remove a standby inhibitor.

    object allOf
    uid: delStandbyInhibitorMsg
  • #38del_all_standby_inhibitors

    ๐Ÿงช Remove all standby inhibitors.

    object allOf
    uid: delAllStandbyInhibitorsMsg
  • #39get_ambient_light

    ๐Ÿ” Get current ambient light intensity.

    object allOf
    uid: getAmbientLightMsg
  • #40ambient_light

    ๐Ÿ” Current ambient light response.

    object allOf
    uid: ambientLightMsg
  • #41reset_configuration

    ๐Ÿงช Reset all settings to default values.

    object allOf
    uid: resetConfigurationMsg
  • #42get_configuration

    ๐Ÿงช Get all system settings.

    object allOf
    uid: getConfigurationMsg
  • #43configuration

    ๐Ÿงช All system settings response.

    object allOf
    uid: configurationMsg
  • #44get_button_cfg

    ๐Ÿงช Get button settings.

    object allOf
    uid: getButtonCfgMsg
  • #45set_button_cfg

    ๐Ÿงช Modify button settings.

    object allOf
    uid: setButtonCfgMsg
  • #46button_cfg

    ๐Ÿงช Button settings response.

    Button backlight configuration.

    Device features:

    • BACKLIGHT: buttons have backlight (UCR2, UCR3).
    • RGB_COLOR: RGB color backlight support (UCR3).
    • ZONES: backlight can be controlled with individual zones (UCR3).

    โš ๏ธ Individual color per zone is not yet supported.

    object allOf
    uid: buttonCfgMsg
  • #47get_device_cfg

    ๐Ÿงช Get remote device settings.

    object allOf
    uid: getDeviceCfgMsg
  • #48set_device_cfg

    ๐Ÿงช Modify remote device settings.

    object allOf
    uid: setDeviceCfgMsg
  • #49device_cfg

    ๐Ÿงช Remote device settings response.

    object allOf
    uid: deviceCfgMsg
  • #50get_display_cfg

    ๐Ÿงช Get display settings.

    object allOf
    uid: getDisplayCfgMsg
  • #51set_display_cfg

    ๐Ÿงช Modify display settings.

    object allOf
    uid: setDisplayCfgMsg
  • #52display_cfg

    ๐Ÿงช Display settings response.

    object allOf
    uid: displayCfgMsg
  • #53get_features_cfg

    ๐Ÿงช Get feature flag settings.

    object allOf
    uid: getFeaturesCfgMsg
  • #54set_features_cfg

    ๐Ÿงช Modify a feature flag.

    object allOf
    uid: setFeaturesCfgMsg
  • #55features_cfg

    ๐Ÿงช Feature flag settings response.

    object allOf
    uid: featuresCfgMsg
  • #56get_haptic_cfg

    ๐Ÿงช Get haptic settings.

    object allOf
    uid: getHapticCfgMsg
  • #57set_haptic_cfg

    ๐Ÿงช Modify haptic settings.

    object allOf
    uid: setHapticCfgMsg
  • #58haptic_cfg

    ๐Ÿงช Haptic settings response.

    object allOf
    uid: hapticCfgMsg
  • #59get_localization_cfg

    ๐Ÿงช Get localization settings.

    object allOf
    uid: getLocalizationCfgMsg
  • #60set_localization_cfg

    ๐Ÿงช Modify localization settings.

    object allOf
    uid: setLocalizationCfgMsg
  • #61localization_cfg

    ๐Ÿงช Localization settings response.

    object allOf
    uid: localizationCfgMsg
  • #62get_timezone_names

    ๐Ÿงช Get all available time zone names.

    object allOf
    uid: getTimezoneNamesMsg
  • #63timezone_names

    ๐Ÿงช Available time zone names response.

    object allOf
    uid: timezoneNamesMsg
  • #64get_localization_countries

    ๐Ÿงช Get available countries for the localization configuration.

    object allOf
    uid: getLocalizationCountriesMsg
  • #65localization_countries

    ๐Ÿงช Available localization countries response.

    object allOf
    uid: localizationCountriesMsg
  • #66get_localization_languages

    ๐Ÿงช Get stored translations or request available translations from the UI.

    The available translations are provided from the UI application.
    Future UI versions might provide new or updated translations.

    If this request is sent to the UI application, the response is stored in the remote-core until new information is available from the UI.

    If this request is received, the stored configuration from the UI application is returned. E.g. the web-configurator requires the available translations.

    object allOf
    uid: getLocalizationLanguagesMsg
  • #67localization_languages

    ๐Ÿงช Available translations response.

    object allOf
    uid: localizationLanguagesMsg
  • #68get_network_cfg

    ๐Ÿงช Get network settings.

    object allOf
    uid: getNetworkCfgMsg
  • #69set_network_cfg

    ๐Ÿ” Modify network settings.

    Change one or multiple network settings.

    โš ๏ธ The ws configuration object is an expert setting intended for support issues. Those settings may not be exposed in a user frontend.

    • The ws object is only returned, after it has been set manually.
    • Settings stay persisted for PATCH requests not containing the ws key.
    • Return and apply current system settings: send a PATCH request with an empty object: `"ws": {}".
    • The ws settings can only be removed with a configuration reset: DELETE /cfg
    • Modifying any ws settings requires a system reboot.
    object allOf
    uid: setNetworkCfgMsg
  • #70network_cfg

    ๐Ÿ” Network settings response.

    object allOf
    uid: networkCfgMsg
  • #71get_software_update_cfg

    ๐Ÿงช Get software update settings.

    object allOf
    uid: getSoftwareUpdateCfgMsg
  • #72set_software_update_cfg

    ๐Ÿงช Modify software update settings.

    Change one or multiple software update settings.

    If check_for_updates is enabled:

    • the device automatically checks for new updates daily. The check happens during a random time within the OTA window time frame ota_window_start - ota_window_end.
    • if a new update is available, the update metadata is immediately downloaded and the firmware update file is scheduled to download.
    • the firmware file will only download if the remote has at least 50% battery charge.
    • if the remote is not in the dock and suspended, the remote will not automatically wake up and the check will be skipped.

    If auto_update is enabled:

    • once the firmware file is downloaded it will be automatically installed in the next OTA check window.
    • the installation will only start if the remote has at least 50% battery charge.

    OTA window fields:

    • the stored values are used if omitted.
    • default values are set if not configured.
    • the time of day corresponds to the configured timezone.
    • for changing the update window, both start and end times are required, otherwise a default will be used.
    • if the end time is before the start time, the window will spawn over midnight, e.g. 23:00:00 - 01:00:00.

    Optional software update channel & token:

    • the default release channel is used if not configured.
    • the stored values are used if omitted.
    • changing the update channel is intended for closed user groups only.
      โš ๏ธ High chance of breaking changes, bugs and loosing data!
    • other channels than default might require an access token in channel_token.
    • โš ๏ธ Changing the update channel or token requires a device restart, otherwise the automated updates will not use the new channel!
    object allOf
    uid: setSoftwareUpdateCfgMsg
  • #73reset_software_update_cfg

    ๐Ÿงช Reset software update settings.

    Set all software update settings to default values and use the default release update channel.

    object allOf
    uid: resetSoftwareUpdateCfgMsg
  • #74software_update_cfg

    ๐Ÿงช Software update settings response.

    object allOf
    uid: softwareUpdateCfgMsg
  • #75get_power_saving_cfg

    ๐Ÿงช Get power saving settings.

    object allOf
    uid: getPowerSavingCfgMsg
  • #76set_power_saving_cfg

    ๐Ÿงช Modify power saving settings.

    object allOf
    uid: setPowerSavingCfgMsg
  • #77power_saving_cfg

    ๐Ÿงช Power saving settings response.

    object allOf
    uid: powerSavingCfgMsg
  • #78get_profile_cfg

    ๐Ÿงช Get profile settings.

    object allOf
    uid: getProfileCfgMsg
  • #79set_profile_cfg

    ๐Ÿงช Modify profile settings.

    object allOf
    uid: setProfileCfgMsg
  • #80profile_cfg

    ๐Ÿงช Profile settings response.

    object allOf
    uid: profileCfgMsg
  • #81get_sound_cfg

    ๐Ÿงช Get sound settings.

    object allOf
    uid: getSoundCfgMsg
  • #82set_sound_cfg

    ๐Ÿงช Modify sound settings.

    object allOf
    uid: setSoundCfgMsg
  • #83sound_cfg

    ๐Ÿงช Sound settings response.

    object allOf
    uid: soundCfgMsg
  • #84get_voice_control_cfg

    ๐Ÿ” Get voice control settings.

    object allOf
    uid: getVoiceControlCfgMsg
  • #85set_voice_control_cfg

    ๐Ÿ” Modify voice control settings.

    object allOf
    uid: setVoiceControlCfgMsg
  • #86voice_control_cfg

    ๐Ÿ” Voice control settings response.

    object allOf
    uid: voiceControlCfgMsg
  • #87get_voice_assistants

    ๐Ÿšง Get available voice assistants.

    object allOf
    uid: getVoiceAssistantsMsg
  • #88voice_assistants

    ๐Ÿšง Voice assistants response.

    object allOf
    uid: voiceAssistantsMsg
  • #89get_entity_types

    ๐Ÿงช Retrieve supported entity types.

    object allOf
    uid: getEntityTypesMsg
    • #entity
  • #90entity_types

    ๐Ÿงช List of supported entity types response.

    object allOf
    uid: entityTypesMsg
    • #entity
  • #91get_entity

    ๐Ÿงช Retrieve a configured entity.

    object allOf
    uid: getEntityMsg
    • #entity
  • #92get_entities

    ๐Ÿงช Search and retrieve configured entities.

    Returns all configured entities, optionally filtered by one or multiple entity types or integrations.

    The text search searches in the entity name, entity identifier and integration name.

    Attention: pagination is active and can be parameterized to return more items per page if required.

    object allOf
    uid: getEntitiesMsg
    • #entity
  • #93entities

    ๐Ÿงช List of configured entities response.

    object allOf
    uid: entitiesMsg
    • #entity
  • #94get_available_entities

    ๐Ÿงช Retrieve the available entities provided by an integration.

    โš ๏ธ At the moment it's only possible to retrieve available entities from one integration at a time.

    • filter.integration_id must be specified!
    • available entities can be filtered by one or multiple entity types.
    • the text search searches in the entity name, entity identifier and area.

    Attention: pagination is active and can be parameterized to return more items per page if required.

    object allOf
    uid: getAvailableEntitiesMsg

    Retrieve the available entities provided by the integration instance.

    • #entity
  • #95available_entities

    ๐Ÿงช List of available entities response.

    object allOf
    uid: availableEntitiesMsg
    • #entity
  • #96get_entity_commands

    ๐Ÿงช Retrieve the available commands of an entity or entity type.

    The commands can either be retrieved from a specific entity or from an entity type:

    • entity_id: only available commands for the given entity are returned. This depends on the entity's features.
    • entity_type: all commands for the given entity type are returned.

    The returned command identifiers are not the standard command identifiers like on or off, but mapping identifiers like light.on and light.color_temperature for the command structure information returned with get_entity_command_metadata or GET /api/cfg/entity/commands.

    This then allows to build a full command request execute_entity_command message with or without parameters.

    object allOf
    uid: getEntityCommandsMsg
    • #entity
  • #97entity_commands

    ๐Ÿงช Available commands of an entity response.

    object allOf
    uid: entityCommandsMsg
    • #entity
  • #98get_entity_command_metadata

    ๐Ÿ” Get entity command definitions.

    Meta-information about the entity commands.

    object allOf
    uid: getEntityCommandMetadataMsg
    • #entity
  • #99entity_command_metadata

    ๐Ÿ” Entity command definitions.

    object allOf
    uid: entityCommandMetadataMsg
    • #entity
  • #100execute_entity_command

    ๐Ÿงช Execute an entity command.

    Optional command data can be provided in attribute params.

    object allOf
    uid: executeEntityCommandMsg
    • #entity
  • #101entity

    ๐Ÿงช Entity information response.

    object allOf
    uid: entityMsg
    • #entity
  • #102entity_change

    ๐Ÿงช Entity change event.

    Emitted if an entity has changed, a new entity has been added or a configured entity has been deleted.

    If an entity state or dynamic attribute has changed (through notification of an integration driver), then only the attributes object is included within new_state. This happens after an entity_command or if the entity is updated manually through a user or an external system, e.g. if it has been switched off.

    If the entity definition has changed, e.g. the name, description or icon has been modified with the web configurator, the full entity data is included within new_state.

    If a complete integration is removed then only an integration_change event is sent, i.e. there won't be individual entity_change events for every removed entity!

    โš ๏ธ This event is also used to indicate the client to reload all entities. This is the case if only event_type: change is set and the entity_id field is missing.

    object allOf
    uid: entityChangeEventMsg
    • #entity
    • #event
  • #103activity_group_change

    ๐Ÿงช Activity group change event.

    Emitted if an activity group has changed, a new group has been added or a group has been deleted.

    โš ๏ธ This event is also used to indicate the client to reload all activity groups. This is the case if only event_type: change is set and the group_id field is missing.

    object allOf
    uid: activityGroupChangeEventMsg
    • #entity
    • #event
  • #104update_entity

    ๐Ÿงช Update an entity.

    Update one or multiple properties of an entity.

    The updated entity object is returned if the entity could be updated.
    In case of an error the default result message is returned with an error code.

    object allOf
    uid: updateEntityMsg
    • #entity
  • #105delete_entity

    ๐Ÿงช Remove a configured entity.

    Delete the configured entity and remove it from all profile pages and groups.

    object allOf
    uid: deleteEntityMsg
    • #entity
  • #106delete_entities

    ๐Ÿงช Remove configured entities.

    Unloads and deletes multiple configured entities, either by integration identifier or by entity identifiers. If a deleted entity is still provided from an integration, it can be reused and will show up again as available entity from its integration.

    โš ๏ธ An empty request body array will delete all configured entities!

    All references to the configured entities will be removed from profile pages and groups.

    This is a best effort operation:

    • unknown entity identifiers are ignored, no error is returned

    Deleted entities will trigger an entity_change event with event_type: DELETE. If a large amount of entities are deleted, a single, generic entity_change event might be sent instead (without an entity_id field).

    object allOf
    uid: deleteEntitiesMsg
    • #entity
  • #107get_dock_count

    ๐Ÿงช Get total number of configured docks.

    By default only active docks are counted. This can be changed with the active query parameter.

    object allOf
    uid: getDockCountMsg
    • #dock
  • #108dock_count

    ๐Ÿงช Total number of configured docks response.

    object allOf
    uid: dockCountMsg
    • #dock
  • #109get_docks

    ๐Ÿงช List configured docks and their connection state.

    Returns all dock configuration with paging. The configuration data is enriched with current connection information. Use the get_dock_count operation to retrieve the total number of defined docking stations.

    By default only active docks are returned. This can be changed with the active query parameter.

    object allOf
    uid: getDocksMsg
    • #dock
  • #110docks

    ๐Ÿงช Configured docks and their connection state response.

    object allOf
    uid: docksMsg
    • #dock
  • #111create_dock

    ๐Ÿงช Create a new dock configuration.

    Manually create and persist a new dock configuration. This is a low-level operation without configuring and setting up the dock as with the setup operations! To establish a session to the dock, the connect operation must be called afterwards.

    • Error 422 is returned if the given service name in dock_id already exists.
    • If custom_ws_url is not specified, the dock address is resolved through an mDNS service name lookup in dock_id.
    • The active flag specifies if the dock will react to connection requests.
    • Non-active docks will not auto-connect and must be enabled first to be used.
    • Non-active docks won't be visible in the web-configurator.
    • If no token is provided the default token is used! The token is used to authenticate the WebSocket connection once a connection to the dock is established.
    • If model is provided it must be one of the known dock model identifiers: UCD2 or YIO1DOCK.
    object allOf
    uid: createDockMsg
    • #dock
  • #112dock

    ๐Ÿงช Configured dock response.

    object allOf
    uid: dockMsg
    • #dock
  • #113delete_all_docks

    ๐Ÿงช Delete all dock configurations.

    โš ๏ธ All defined dock configurations will be irrevocably deleted!

    Active dock sessions will be disconnected and the persisted dock configurations removed.

    object allOf
    uid: deleteAllDocksMsg
    • #dock
  • #114get_dock

    ๐Ÿงช Get dock configuration.

    Returns the dock configuration, enriched with the current session information if a dock connection is established.

    object allOf
    uid: getDockMsg
    • #dock
  • #115update_dock

    ๐Ÿงช Change dock configuration like auto-connect or access token.

    Update one or more dock fields.

    • If the dock is in an active connection state, then the name, token and wifi values are persisted in the dock if provided in the request. The request fails with 503 service unavailable if the configuration can't be set in the docking station.
    • An empty custom_ws_url value will remove the custom URL.
    • If the dock is not active, the values are only stored in the remote. A changed token will be used for the next connection attempt.
    object allOf
    uid: updateDockMsg
    • #dock
  • #116dock_connection_command

    ๐Ÿงช Start or stop a dock connection.

    Establish or stop a session to a specific or all active docks.

    object allOf
    uid: dockConnectionCommandMsg
    • #dock
  • #117delete_dock

    ๐Ÿงช Delete dock configuration.

    โš ๏ธ The dock configuration will be irrevocably deleted!

    An active dock session will be disconnected and the persisted dock configuration removed.

    object allOf
    uid: deleteDockMsg
    • #dock
  • #118dock_command

    ๐Ÿงช Send a dock command.

    The following command values are defined:

    • SET_LED_BRIGHTNESS: set the maximum brightness of the front indicator LED. Set the 0..100 percentage as string parameter in the value field.
    • IDENTIFY: identify the dock with blinking the indicator LED.
    • REMOTE_LOW_BATTERY: trigger the low battery status indicator on the dock.
    • REMOTE_CHARGED: trigger the remote charged indicator on the dock.
    • REMOTE_NORMAL: trigger the normal remote operation mode on the dock.
    • REBOOT: reboot the dock.
    • RESET: โš ๏ธ factory reset the dock. Requires administrator privileges.
      The dock configuration will be deleted from the remote.
    object allOf
    uid: dockCommandMsg
    • #dock
  • #119get_dock_discovery_status

    ๐Ÿงช Get docking station discovery status.

    Returns the current discovery status and any discovered docks.

    object allOf
    uid: getDockDiscoveryStatusMsg
    • #dock
  • #120dock_discovery_status

    ๐Ÿงช Docking station discovery status response.

    object allOf
    uid: dockDiscoveryStatusMsg
    • #dock
  • #121start_dock_discovery

    ๐Ÿงช Start discovery of new docking stations.

    Start device discovery over Bluetooth and mDNS. Bluetooth or network discovery can be disabled with a query parameter. By default the discovery automatically stops after 30 seconds. Use the get_dock_discovery_status status request to check on discovered devices or stop_dock_discovery to stop discovery.

    By default only new network devices are returned. If a dock is already configured it will be omitted from the results, unless the query parameter new=false is set. Docks with Bluetooth enabled are always returned, since this usually means that the dock needs to be re-configured.

    • If BT is disabled in the remote, the bt parameter is ignored.
    • Emits the WebSocket event dock_discovery with event_type: START when discovery starts.
    • For each discovered device the WebSocket event dock_discovery with event_type: DISCOVER is emitted.
    • This operation clears any old discovered devices and won't be accessible anymore with the GET operation.
    object allOf
    uid: startDockDiscoveryMsg
    • #dock
  • #122stop_dock_discovery

    ๐Ÿงช Stop discovery of new docking stations.

    Stops the device discovery. The current discovery status is returned in the response. Already discovered devices won't be returned and can still be retrieved with the get_dock_discovery_status operation.

    Emits the WebSocket event dock_discovery with event_type: STOP.

    object allOf
    uid: stopDockDiscoveryMsg
    • #dock
  • #123get_dock_discovery_device

    ๐Ÿงช Get docking station discovery device status.

    Returns the discovered docking station device.

    object allOf
    uid: getDockDiscoveryDeviceMsg
    • #dock
  • #124dock_discovery_device

    ๐Ÿงช Docking station discovery device status response.

    object allOf
    uid: dockDiscoveryDeviceMsg
    • #dock
  • #125exec_cmd_on_discovered_dock

    ๐Ÿงช Execute command on a discovered docking station.

    Perform a WebSocket connection test with a discovered docking station. If the dock requires an API token, it must be specified in the request body.
    The IDENTIFY command also blinks the status LED on the dock.

    Response status codes:

    • 200: successful operation: the connection test was successful and docking station metadata could be retrieved.
    • 404: discovered dock with dock_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with DELETE /docks/discover.
    • 503: docking station connection could not be established.
    object allOf
    uid: execCmdOnDiscoveredDockMsg
    • #dock
  • #126dock_system_info

    ๐Ÿงช Dock system information response.

    object allOf
    uid: dockSystemInfoMsg
    • #dock
  • #127get_dock_setup_processes

    ๐Ÿงช Get current dock setup processes.

    Return a list of all active setup process identifiers.

    object allOf
    uid: getDockSetupProcessesMsg
    • #dock
  • #128dock_setup_processes

    ๐Ÿงช Current dock setup processes response.

    object allOf
    uid: dockSetupProcessesMsg
    • #dock
  • #129create_dock_setup

    ๐Ÿงช Start setting up a new docking station.

    Create a new setup process from a discovered dock or from a manually provided dock address.

    • If there's already a setup process running for the given dock id, status code 409 is returned.
    • Emits the WebSocket event dock_setup_change with event_type: START when this operation returns 201.

    Start setup from dock discovery:

    • The required request data can be obtained from the /api/docks/discover endpoints when searching for docking stations over Bluetooth or Ethernet. Simply provide the returned DockDiscovery data object (which is a super set of the required data to start a setup process).
    • The returned id in the DockSetupInfo response will be the identifier for the next PUT /docks/setup/:id call to provide additional data.

    Manual setup:

    • A dock identifier will automatically be created and returned in DockSetupInfo.
    • The dock must be reachable on the network with the provided custom_ws_url and optional token. Otherwise, status code 503 is returned.
    • The setup process is automatically started after a successful POST request, no call to PUT /docks/setup/:id is required.

    Response status codes:

    • 201: setup process successfully started. Use GET /docks/setup/:id to poll for status updates, or listen to WebSocket dock_setup_change event messages.
    • 400: invalid data in request body.
    • 409: a setup process is already running. Either wait until finished, or abort it.
    • 503: service not available to setup docking station.
      E.g. Bluetooth is disabled and therefore the docking station cannot be setup over Bluetooth. Either enable Bluetooth or setup the dock over Ethernet.
    object allOf
    uid: createDockSetupMsg
    • #dock
  • #130dock_setup_status

    ๐Ÿงช Dock setup information response.

    object allOf
    uid: dockSetupStatusMsg
    • #dock
  • #131stop_all_dock_setups

    ๐Ÿงช Abort and remove all setup processes.

    Stop all setup processes at the next possible operation and remove all setup process information.

    object allOf
    uid: stopAllDockSetupsMsg
    • #dock
  • #132get_dock_setup_status

    ๐Ÿงช Get docking station setup status.

    Poll operation to retrieve the current docking station setup state. See the state and error fields in the response message. There are also WebSocket dock_setup_change event messages for state changes to avoid polling.

    Defined setup states:

    • NEW: setup has not yet been started. Use the PUT operation to provide the required data and to start setting up the dock.
    • CONFIGURING: setup data is currently being transferred to the dock.
    • RESTARTING: dock has been configured and is restarting to integrate into the network.
    • OK: setup process has been completed successfully, the dock can now be used.
    • ERROR: the setup process failed. Check the error field for more information.
    object allOf
    uid: getDockSetupStatusMsg
    • #dock
  • #133start_dock_setup

    ๐Ÿงช Setup docking station.

    Set required data to start the setup process and configure the docking station. When using Bluetooth the WiFi network name and credentials must be provided to connect the dock to the WiFi network.

    The state field in the response message indicate the current state of the setup process. Use the GET operation to poll for state updates or listen to the corresponding WebSocket dock_setup_change event messages with event_type: SETUP.

    object allOf
    uid: startDockSetupMsg
    • #dock
  • #134stop_dock_setup

    ๐Ÿงช Abort the dock setup process.

    Stop the setup process at the next possible operation and remove the setup process information.
    To start a new setup process, use the POST /docks/setup operation again.

    Emits the WebSocket event dock_setup_change with event_type: STOP.

    object allOf
    uid: stopDockSetupMsg
    • #dock
  • #135get_wifi_status

    ๐Ÿงช Get WiFi status.

    object allOf
    uid: wifiGetStatusMsg
    • #wifi
  • #136wifi_status

    ๐Ÿงช WiFi status.

    object allOf
    uid: wifiStatusMsg
    • #wifi
  • #137wifi_command

    ๐Ÿงช WiFi connection handling.

    Perform one of the following commands on the WLAN interface:

    • DISCONNECT: Disconnect and wait for REASSOCIATE or RECONNECT command before connecting again.
    • RECONNECT: Connect if disconnected (i.e. like REASSOCIATE, but only connect if in disconnected state).
    • REASSOCIATE: Force reassociation.
    • ENABLE_ALL_NETWORKS: Enable all network connections and start connecting to a network if in disconnected state.
    • DISABLE_ALL_NETWORKS: Disable all network connections and disconnect if in connected state.

    โš ๏ธAttention: ENABLE_ALL_NETWORKS and DISABLE_ALL_NETWORKS will persist the state! I.e. if all networks are disabled and the device is restarted afterwards, no WiFi connection will be established.

    object allOf
    uid: wifiCommandMsg
    • #wifi
  • #138wifi_scan_start

    ๐Ÿงช Start discovery of WiFi access points.

    Request a new BSS scan. A scan usually takes a few seconds and the current state is returned with the get_wifi_scan_status operation, together with the already found access points.

    object allOf
    uid: wifiScanStartMsg
    • #wifi
  • #139wifi_scan_stop

    ๐Ÿงช Stop discovery of WiFi access points.

    Stops the access point discovery. The current discovery status is returned in the response.

    object allOf
    uid: wifiScanStopMsg
    • #wifi
  • #140get_wifi_scan_status

    ๐Ÿงช Get discovered WiFi access points.

    Returns the current discovery status and any discovered access points.

    object allOf
    uid: wifiGetScanStatusMsg
    • #wifi
  • #141wifi_scan_status

    ๐Ÿงช Discovered WiFi access points.

    object allOf
    uid: wifiScanStatusMsg
    • #wifi
  • #142get_all_wifi_networks

    ๐Ÿงช Get configured WiFi networks.

    object allOf
    uid: wifiGetAllNetworksMsg
    • #wifi
  • #143wifi_networks

    ๐Ÿงช Configured WiFi networks.

    object allOf
    uid: wifiNetworksMsg
    • #wifi
  • #144add_wifi_network

    ๐Ÿงช Create a new WiFi network configuration.

    Add a new network configuration for the given SSID.
    For an open network without password the password field must be omitted (do not send an empty password value).

    โš ๏ธ Only WPA-PSK (pre shared keys) and open networks are supported!

    object allOf
    uid: wifiAddNetworkMsg
    • #wifi
  • #145del_all_wifi_networks

    ๐Ÿงช Delete all configured WiFi networks.

    Disconnects the WiFi network and removes all network configurations.

    โš ๏ธ Attention: the network configuration is automatically persisted and the network configuration cannot be retrieved anymore!

    object allOf
    uid: wifiDelAllNetworksMsg
    • #wifi
  • #146get_wifi_network

    ๐Ÿงช Get WiFi network configuration.

    object allOf
    uid: wifiGetNetworkMsg
    • #wifi
  • #147wifi_network

    ๐Ÿงช WiFi network configuration.

    object allOf
    uid: wifiNetworkMsg
    • #wifi
  • #148update_wifi_network

    ๐Ÿงช Change WiFi network configuration.

    Set a new WiFi network password.

    object allOf
    uid: wifiUpdateNetworkMsg
    • #wifi
  • #149wifi_network_command

    ๐ŸงชWiFi network connection handling.

    Perform one of the following commands on a network configuration:

    • ENABLE: Enable a network. If no network is connected, it will be tried to connect to this network.
    • DISABLE: Disable a network. If the network is currently connected it will be disconnected.
    • SELECT: Select the given network and disable all others.

    โš ๏ธ Attention: all network changes (enabled or disabled) are persisted!

    object allOf
    uid: wifiNetworkCommandMsg
    • #wifi
  • #150del_wifi_network

    ๐Ÿงช Delete a configured WiFi network.

    The given network is removed from the configuration and disconnected if currently connected.

    โš ๏ธ Attention: the network configuration is automatically persisted and the removed network configuration cannot be retrieved anymore!

    object allOf
    uid: wifiDelNetworkMsg
    • #wifi
  • #151wifi_change

    ๐Ÿงช WiFi change event.

    Emitted if the WiFi status changed, e.g. connected or disconnected to an access point, or if a WiFi network scan finished.

    object allOf
    uid: wifiChangeEventMsg
    • #event
  • #152bt_pairing_started

    ๐Ÿ” Inform user that pairing has started.

    Emitted if a central started pairing with the Remote.

    object allOf
    uid: btPairingStartedEventMsg
    • #event
  • #153bt_pairing_auth_request

    ๐Ÿ” Request pairing authorization from the user.

    Depending on authentication requirements, IO capabilities, etc. a different type of authentication is requested. The client must respond with the bt_pairing_response event.

    object allOf
    uid: btPairingAuthRequestEventMsg
    • #event
  • #154bt_pairing_complete

    ๐Ÿ” Bonding process has finished.

    This event is emitted after the bonding process, either with a success state or an error code if bonding failed.

    object allOf
    uid: btPairingCompleteEventMsg
    • #event
  • #155bt_pairing_response

    ๐Ÿ” Action to bt_pairing_auth_request event.

    This request needs to be sent for a bt_pairing_auth_request event:

    • Passkey request: either provide the passkey entered by the user, or decline it with confirm: false.
    • NumericComparison request: confirm or decline with confirm: true | false.
    object allOf
    uid: btPairingResponseMsg
    • #event
  • #156get_profiles

    ๐Ÿงช Retrieve all profiles.

    object allOf
    uid: getProfilesMsg
    • #profile
  • #157profiles

    ๐Ÿงช List of available profiles response.

    object allOf
    uid: profilesMsg
    • #profile
  • #158get_profile

    ๐Ÿงช Retrieve the specified profile.

    object allOf
    uid: getProfileMsg
    • #profile
  • #159profile

    ๐Ÿงช Profile data response.

    object allOf
    uid: profileMsg
    • #profile
  • #160get_active_profile

    ๐Ÿงช Retrieve the active profile.

    If no profile exists, or no profile is set active, 404 is returned.

    object allOf
    uid: getActiveProfileMsg
    • #profile
  • #161switch_profile

    ๐Ÿงช Switch active profile.

    The administrator PIN in admin_pin is required to switch from a restricted to a normal profile. If the current profile is a restricted profile and the pin is missing, error 401 is returned.

    object allOf
    uid: switchProfileMsg
    • #profile
  • #162add_profile

    ๐Ÿงช Add a new profile.

    There are two different types of profiles:

    • Normal profile (default): can do anything, change settings, add pages, entities, integrations, etc.
    • Restricted profile: intended for guests or children, who can only use the remote, but cannot change settings.

    The admin PIN is required to switch from a restricted to a normal profile. It can be defined in settings.

    • Switching away from a restricted profile will prompt the user to enter the admin PIN.
    • Switching to a restricted profile can be done without entering the admin PIN.

    Profile request object:

    • profile_id is optional and auto-generated if not specified. Otherwise it needs to be a unique profile identifier.
    • name is mandatory and must be unique.
    • if the first profile is added, it is automatically set as the active profile.
    object allOf
    uid: addProfileMsg
    • #profile
  • #163update_profile

    ๐Ÿงช Update a profile.

    Update one or multiple properties of a profile. A missing property will not update its current value.

    • profile_id is mandatory and can't be changed.
    • an empty icon value removes an existing icon identifier.
    • a missing pages property will not change the page order.
    • โš ๏ธ an empty pages array removes all pages and groups in the profile!
    • โš ๏ธ missing page identifiers in the pages array will remove the page configuration!
    object allOf
    uid: updateProfileMsg
    • #profile
  • #164delete_profile

    ๐Ÿงช Delete the specified profile.

    All profile related pages and groups are also deleted.

    object allOf
    uid: deleteProfileMsg
    • #profile
  • #165delete_all_profiles

    ๐Ÿงช Delete all profiles.

    This also deletes all pages and groups.

    object allOf
    uid: deleteAllProfilesMsg
    • #profile
  • #166active_profile_change

    ๐Ÿงช Active profile change event.

    Emitted if the active profile changed.

    object allOf
    uid: activeProfileChangeEventMsg
    • #profile
    • #event
  • #167profile_change

    ๐Ÿงช Profile change event.

    Emitted if a profile configuration, related profile page or group has been changed, added or deleted.

    object allOf
    uid: profileChangeEventMsg
    • #profile
    • #event
  • #168get_pages

    ๐Ÿงช Retrieve all UI pages of a profile.

    object allOf
    uid: getPagesMsg
    • #profile
  • #169pages

    ๐Ÿงช List of defined UI pages response.

    object allOf
    uid: pagesMsg
    • #profile
  • #170get_page

    ๐Ÿงช Retrieve the specified UI page.

    object allOf
    uid: getPageMsg
    • #profile
  • #171page

    ๐Ÿงช UI page data response.

    object allOf
    uid: pageMsg
    • #profile
  • #172add_page

    ๐Ÿงช Create a new UI page and add to profile.

    • profile_id is mandatory.
    • page_id is not required and is created automatically.
    • name is mandatory and must be unique within the profile.
    object allOf
    uid: addPageMsg
    • #profile
  • #173update_page

    ๐Ÿงช Update a UI page.

    • profile_id and page_id are mandatory.
    object allOf
    uid: updatePageMsg
    • #profile
  • #174delete_page

    ๐Ÿงช Delete a UI page.

    object allOf
    uid: deletePageMsg
    • #profile
  • #175delete_pages_in_profile

    ๐Ÿงช Delete all pages of a profile

    object allOf
    uid: deletePagesInProfileMsg
    • #profile
  • #176get_groups

    ๐Ÿงช Retrieve all UI groups of a profile.

    object allOf
    uid: getGroupsMsg
    • #profile
  • #177groups

    ๐Ÿงช List of defined UI groups response.

    object allOf
    uid: groupsMsg
    • #profile
  • #178get_group

    ๐Ÿงช Retrieve the specified UI group.

    object allOf
    uid: getGroupMsg
    • #profile
  • #179group

    ๐Ÿงช UI group data response.

    object allOf
    uid: groupMsg
    • #profile
  • #180add_group

    ๐Ÿงช Create a new UI group and add to profile.

    • profile_id is mandatory.
    • group_id is not required and is created automatically.
    • name is mandatory and must be unique within the profile.
    object allOf
    uid: addGroupMsg
    • #profile
  • #181update_group

    ๐Ÿงช Update a UI group.

    • profile_id and group_id are mandatory.
    object allOf
    uid: updateGroupMsg
    • #profile
  • #182delete_group

    ๐Ÿงช Delete a UI group.

    object allOf
    uid: deleteGroupMsg
    • #profile
  • #183delete_groups_in_profile

    ๐Ÿงช Delete all groups in a profile.

    object allOf
    uid: deleteGroupsInProfileMsg
    • #profile
  • #184get_integration_status

    ๐Ÿงช Retrieve an overview of the integration instances and their current connection state.

    object allOf
    uid: getIntegrationStatusMsg
    • #integration
  • #185integration_status

    ๐Ÿงช Summary information of the integration instances.

    object allOf
    uid: integrationStatusMsg
    • #integration
  • #186integration_cmd

    ๐Ÿงช Execute an integration command.

    Connect or disconnect integration instances.

    If integration_id is specified, then the command only applies to the given integration, otherwise to all integration instances.

    object allOf
    uid: integrationCmdMsg
    • #integration
  • #187integration_driver_cmd

    ๐Ÿงช Execute an integration driver command.

    Start or stop integration drivers.

    If driver_id is specified, then the command only applies to the given driver, otherwise to all integration drivers.

    object allOf
    uid: integrationDriverCmdMsg
    • #integration
  • #188get_integration_driver_count

    ๐Ÿงช Get total number of registered integration drivers.

    object allOf
    uid: getIntegrationDriverCountMsg
    • #integration
  • #189integration_driver_count

    ๐Ÿงช Total number of registered integration drivers response.

    object allOf
    uid: integrationDriverCountMsg
    • #integration
  • #190get_integration_drivers

    ๐Ÿงช Retrieve all registered integration drivers.

    object allOf
    uid: getIntegrationDriversMsg
    • #integration
  • #191integration_drivers

    ๐Ÿงช List of registered integration drivers response.

    object allOf
    uid: integrationDriversMsg
    • #integration
  • #192register_integration_driver

    ๐Ÿงช Register a new integration driver.

    object allOf
    uid: registerIntegrationDriverMsg
    • #integration
  • #193get_integration_driver

    ๐Ÿงช Retrieve detail information of an integration driver.

    object allOf
    uid: getIntegrationDriverMsg
    • #integration
  • #194integration_driver

    ๐Ÿงช Detail information of an integration driver response.

    object allOf
    uid: integrationDriverMsg
    • #integration
  • #195update_integration_driver

    ๐Ÿงช Modify a configured integration driver.

    object allOf
    uid: updateIntegrationDriverMsg
    • #integration
  • #196delete_integration_driver

    ๐Ÿงช Remove an integration driver.

    Unloads and deletes an integration driver with all instances and provided entities.

    Attention: all references to the integration driver will be removed! This includes all driver instances, provided entities and their references in profile pages and groups.

    object allOf
    uid: deleteIntegrationDriverMsg
    • #integration
  • #197get_integration_count

    ๐Ÿงช Get total number of integration instances.

    object allOf
    uid: getIntegrationCountMsg
    • #integration
  • #198integration_count

    ๐Ÿงช Total number of integration instances response.

    object allOf
    uid: integrationCountMsg
    • #integration
  • #199get_integrations

    ๐Ÿงช Retrieve all loaded integrations.

    Returns all integration instances, optionally filtered by type or enabled state.

    object allOf
    uid: getIntegrationsMsg
    • #integration
  • #200integrations

    ๐Ÿงช List of loaded integrations response.

    object allOf
    uid: integrationsMsg
    • #integration
  • #201create_integration

    ๐Ÿงช Create a new integration instance from driver.

    Create an integration driver instance and associate it with the driver. For simple integration drivers there's a 1:1 relationship only between an instance and driver. For multi-device drivers, each device corresponds to an integration instance.

    • the integration_id is automatically created by the system to make it unique over all integrations.
    • for multi-device drivers the device_id must be specified and may not already exist in another instance of the same driver.
    • the driver's name is used by default if name isn't specified.
    • the instance is active by default if enabled isn't specified.
    object allOf
    uid: createIntegrationMsg
    • #integration
  • #202integration

    ๐Ÿงช Integration instance information response.

    object allOf
    uid: integrationMsg
    • #integration
  • #203get_integration

    ๐Ÿงช Get an integration instance.

    object allOf
    uid: getIntegrationMsg
    • #integration
  • #204update_integration

    ๐Ÿงช Modify a configured integration instance.

    Modify one or several properties of an integration instance.
    See update model description on how to update or delete an existing property.

    The integration driver of an instance cannot be changed and will be ignored if provided in the request.

    object allOf
    uid: updateIntegrationMsg
    • #integration
  • #205delete_integration

    ๐Ÿงช Remove an integration instance.

    Unloads and deletes an integration instance.

    Attention: all references to the integration instance will be removed! This includes configured entities and their references in profile pages and groups.

    object allOf
    uid: deleteIntegrationMsg
    • #integration
  • #206configure_entity_from_integration

    ๐Ÿงช Configure an available entity.

    Configure a new UC Remote entity from an available integration entity. Once configured, the entity will no longer show up as available entity (unless the all filter is set).

    The entity name, icon and description fields may be changed. If not specified in the request the values from the available entity are used.

    In case of an error the default result message is returned with an error code.

    object allOf
    uid: configureEntityFromIntegrationMsg
    • #integration
  • #207configure_entities_from_integration

    ๐Ÿงช Configure multiple available entities.

    Configure multiple new UC Remote entities from available integration entities. Once configured, the entities will no longer show up as an available entity (unless the filter=ALL query parameter is set).

    If entity_ids is not provided or is empty, all entities from the integration are configured.

    Use message configure_entity_from_integration to configure a single entity and optionally rename it or change its icon.

    This is a best effort operation:

    • if an entity is already configured, it is ignored and not returned in the response.
    • unknown entity identifiers are ignored, no error is returned.

    Every newly configured entity will trigger an entity_change event.

    object allOf
    uid: configureEntitiesFromIntegrationMsg
    • #integration
  • #208get_integration_discovery_status

    ๐Ÿงช Get external integration driver discovery status.

    Returns the current discovery status and the discovered integration drivers.

    Use start_integration_discovery to clear old results and start a new discovery.

    object allOf
    uid: getIntegrationDiscoveryStatusMsg
    • #integration
  • #209integration_discovery_status

    ๐Ÿงช External integration driver discovery status response.

    object allOf
    uid: integrationDiscoveryStatusMsg
    • #integration
  • #210start_integration_discovery

    ๐Ÿงช Start discovery of external integration drivers.

    Start integration driver discovery on the network with mDNS. By default the discovery automatically stops after 30 seconds. Use the get_integration_discovery_status request to check on discovered devices or stop_integration_discovery to stop discovery.

    By default only new integration drivers are returned. If a driver is already configured it will be omitted from the results, unless the query parameter new=false is set.

    • Previously discovered integrations are removed, only newly discovered integrations will be returned.
    • Emits the WebSocket event integration_discovery with event_type: START when discovery starts.
    • For each discovered driver the WebSocket event integration_discovery with event_type: DISCOVER is emitted.
    object allOf
    uid: startIntegrationDiscoveryMsg
    • #integration
  • #211stop_integration_discovery

    ๐Ÿงช Stop discovery of external integration drivers.

    Stops the driver discovery and returns the current discovery status in the response.

    Emits the WebSocket event integration_discovery with event_type: STOP.

    object allOf
    uid: stopIntegrationDiscoveryMsg
    • #integration
  • #212get_discovered_integration_driver

    ๐Ÿงช Get integration driver discovery information.

    Returns the discovered integration driver.

    object allOf
    uid: getDiscoveredIntegrationDriverMsg
    • #integration
  • #213discovered_integration_driver

    ๐Ÿงช Integration driver discovery information.

    object allOf
    uid: discoveredIntegrationDriverMsg
    • #integration
  • #214get_discovered_intg_driver_metadata

    ๐Ÿ‘ท Execute connection test and fetch metadata from discovered integration driver.

    Perform a driver connection test with a discovered driver. If the driver requires a token, it must be specified in the request data.

    Response status codes:

    • 200: successful operation: the connection test was successful and driver metadata could be retrieved.
    • 404: discovered driver with driver_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with starting a new discovery.
    • 503: integration driver connection could not be established.
    object allOf
    uid: getDiscoveredIntgDriverMetadataMsg
    • #integration
  • #215configure_discovered_integration_driver

    ๐Ÿงช Register a discovered integration driver.

    Register a discovered integration driver:

    • establish communication with the driver.
      • if the driver requires a password, it must be provided in the request.
      • the discovered driver name and url can be overridden.
    • fetch metadata from the driver.
    • check compatability.
    • register the driver and connection parameters in the remote.

    After a successful registration the setup process of the driver can be started to configure the integration. The required setup data is described in the returned setup_data_schema and the provided values by the user must be passed to the setup_integration request.

    Response status codes:

    • 400: invalid data in request body.
    • 404: no discovered driver found for given driver_id.
    • 409: integration driver is already registered.
    • 503: integration driver communication error. Either driver is not reachable or communication failed.
    object allOf
    uid: configureDiscoveredIntegrationDriverMsg
    • #integration
  • #216get_integration_setup_processes

    ๐Ÿงช Get current integration setup processes.

    Return a list of all active setup process identifiers. The returned ids can be used with the set_integration_user_data and stop_integration_setup messages to continue or abort a setup process.

    object allOf
    uid: getIntegrationSetupProcessesMsg
    • #integration
  • #217integration_setup_processes

    ๐Ÿงช Current integration setup processes response.

    Return a list of all active setup process identifiers.

    object allOf
    uid: integrationSetupProcessesMsg
    • #integration
  • #218setup_integration

    ๐Ÿงช Start setting up a new integration driver.

    Start a new setup process for the given integration driver and provided setup data, or reconfigure an existing driver.

    • This operation immediately starts the driver communication and setup process.
    • There may only be one active setup process per driver, otherwise status code 409 is returned.

    The returned id in the IntegrationSetupInfo response will be the identifier for the further setup operations with the set_integration_user_data and stop_integration_setup requests. Once the setup process is successfully finished, an integration instance is created. A setup process can be simple and fully automatic, but may also require user interaction and further communication with the set_integration_user_data message.

    Emits the WebSocket event integration_setup_change with event_type: START.

    Request body:

    • name: optional integration name. If not specified the name of the integration driver is used.
    • setup_data: optional driver setting values corresponding to the driver's setup_data_schema object.
    • reconfigure: set to true to reconfigure an already configured driver. The configuration options and behaviour is driver dependent.

    Response status codes:

    • 400: invalid data in request body. E.g. setting the reconfigure flag for a new driver which is not yet configured.
    • 404: specified driver_id in request body does not exist.
    • 409: a setup process for the given driver_id already exists. Either continue or abort existing process.
    • 422: the setup process cannot be used: either the integration is already configured or doesn't allow to be set up again.
    • 503: integration driver communication error. Either driver is not reachable or communication failed.
    object allOf
    uid: setupIntegrationMsg
    • #integration
  • #219integration_setup_info

    ๐Ÿงช Integration setup information response.

    object allOf
    uid: integrationSetupInfoMsg
    • #integration
  • #220stop_all_integration_setups

    ๐Ÿงช Abort and remove all setup processes.

    Stop all setup processes at the next possible operation and remove all setup process information.
    Depending on the integration driver, a started setup process cannot be aborted.

    โš ๏ธ This stops all setup processes, not just for the current session!

    object allOf
    uid: stopAllIntegrationSetupsMsg
    • #integration
  • #221get_integration_setup_status

    ๐Ÿงช Get integration driver setup status.

    Poll operation to retrieve the current integration driver setup state. See the state and error fields in the response message. There are also WebSocket integration_setup_change event messages for state changes to avoid polling.

    Defined setup states:

    • SETUP: setup is running and configuring the integration.
    • WAIT_USER_ACTION: user input is required to continue the setup process. See require_user_action in response for the required user input. Provide the requested data with the PUT operation.
    • OK: setup process has been completed successfully, the integration driver can now be used.
    • ERROR: the setup process failed. Check the error field for more information.
    object allOf
    uid: getIntegrationSetupStatusMsg
    • #integration
  • #222set_integration_user_data

    ๐Ÿงช Provide requested integration setup data.

    Set required data to configure the integration driver or continue the setup process.

    Defined user actions to set in the request body action field:

    • input_values: if the user was requested to enter settings, e.g. connection or credential parameters to a device or service.
    • confirm: response to the user action confirmation. Set to true if the user had to perform an action like pressing a button on a device and then confirms the action with continuing the setup process.
      The false value is prepared for yes / no choices.

    The state field in the response message indicate the current state of the setup process. Use the get_integration_setup_status message to poll for state updates or listen to the corresponding WebSocket integration_setup_change event messages with event_type: SETUP.

    object allOf
    uid: setIntegrationUserDataMsg
    • #integration
  • #223stop_integration_setup

    ๐Ÿงช Abort the integration driver setup process.

    Stop the setup process at the next possible operation and remove the setup process information.
    To start a new setup process, use the setup_integration request again.

    Depending on the integration driver, a started setup process cannot be aborted.

    Emits the WebSocket event integration_setup_change with event_type: STOP.

    object allOf
    uid: stopIntegrationSetupMsg
    • #integration
  • #224get_event_channels

    ๐Ÿงช Retrieve available event channels for the current session.

    Depending on the security role not all event subscriptions may be available.

    object allOf
    uid: getEventChannelsMsg
    • #event
  • #225event_channels

    ๐Ÿงช Available subscriptions for the current session.

    Returns all subscribed event channels.

    object allOf
    uid: eventChannelsMsg
    • #event
  • #226subscribe_events

    ๐Ÿงช Subscribe to event channels.

    Subscribe to one or multiple event channels.

    • The special all channel will deliver all available events and clear all other subscriptions for the session.
    • If the session is already subscribed to the all channel, any other channels are ignored.
    • The special entities channel will deliver all entity and activity-group related events. This includes all entity-type channels (entity_###) and the activity_group channel.
    • Depending on the security role not all event subscriptions may be available.
    object allOf
    uid: subscribeEventsMsg
    • #event
  • #227get_event_subscriptions

    ๐Ÿงช Retrieve the active event channel subscriptions.

    object allOf
    uid: getEventSubscriptionsMsg
    • #event
  • #228unsubscribe_events

    ๐Ÿงช Unsubscribe from event channels.

    object allOf
    uid: unsubscribeEventsMsg
    • #event
  • #229event_subscriptions

    ๐Ÿงช Event channel subscription status.

    Response to subscribe_events, unsubscribe_events and get_event_subscriptions.

    object allOf
    uid: eventSubscriptionsMsg
    • #event
  • #230warning

    ๐Ÿ” System warning event.

    Emitted for important system events like low battery or shutdown events.

    object allOf
    uid: warningEventMsg
    • #event
  • #231integration_driver_change

    ๐Ÿงช Integration driver change event.

    Emitted if an integration driver has changed, a new driver has been added or a configured driver has been deleted.

    object allOf
    uid: integrationDriverChangeEventMsg
    • #integration
    • #event
  • #232integration_change

    ๐Ÿงช Integration change event.

    Emitted if an integration instance has changed, a new instance has been added or a configured instance has been deleted.

    object allOf
    uid: integrationChangeEventMsg
    • #integration
    • #event
  • #233integration_state

    ๐Ÿงช Integration state event.

    Emitted if the connection state of an integration driver or instance has changed.

    object allOf
    uid: integrationStateEventMsg
    • #integration
    • #event
  • #234configuration_change

    ๐Ÿงช System configuration change event.

    Emitted if a system setting has changed.

    The msg_data.new_state object only contains the configuration object of the setting that has changed and not the full system configuration.

    object allOf
    uid: configurationChangeEventMsg
    • #event
  • #235ir_learning

    ๐Ÿงช IR code learn event.

    Emitted if learning mode is started, stopped or a new IR code was learned from an IR emitter device.

    object allOf
    uid: irLearningEventMsg
    • #event
  • #236dock_change

    ๐Ÿงช Dock change event.

    Emitted if a dock configuration has changed.

    object allOf
    uid: dockChangeEventMsg
    • #event
  • #237dock_state

    ๐Ÿงช Dock state event.

    Emitted if the connection state of a dock has changed.

    object allOf
    uid: dockStateEventMsg
    • #event
  • #238dock_discovery

    ๐Ÿงช Docking station discovery event.

    Emitted if dock discovery is started, stopped or a new dock was discovered on the network or via Bluetooth.

    object allOf
    uid: dockDiscoveryEventMsg
    • #event
  • #239dock_setup_change

    ๐Ÿงช Docking station setup state change event.

    Emitted for all dock setup flow state changes.

    object allOf
    uid: dockSetupChangeEventMsg
    • #event
  • #240dock_update_change

    ๐Ÿงช Docking station firmware update change event.

    Emitted for firmware update and progress state changes.

    object allOf
    uid: dockUpdateChangeEventMsg
    • #event
  • #241integration_discovery

    ๐Ÿงช Integration discovery event.

    Emitted if integration discovery is started, stopped or a new integration was discovered on the network.

    object allOf
    uid: integrationDiscoveryEventMsg
    • #event
  • #242integration_setup_change

    ๐Ÿงช Integration setup state change event.

    Emitted for all integration setup flow state changes.

    object allOf
    uid: integrationSetupChangeEventMsg
    • #event
  • #243software_update

    ๐Ÿงช Software update event.

    Emitted during a system update to receive start, stop and progress events.

    object allOf
    uid: softwareUpdateEventMsg
    • #event
  • #244power_mode_change

    ๐Ÿงช Power mode change event.

    Emitted when the power saving mode changes.

    object allOf
    uid: powerModeChangeEventMsg
    • #event
  • #245battery_status

    ๐Ÿงช Battery status event.

    Emitted when the battery status changes.

    object allOf
    uid: batteryStatusEventMsg
    • #event
  • #246ambient_light_change

    ๐Ÿ” Ambient light change event.

    Emitted when the ambient light changes during normal power mode.

    object allOf
    uid: ambientLightChangeEventMsg
    • #event

Schemas

  • object
    uid: commonReq

    Common request message properties.

  • object
    uid: commonResp

    Common response message properties.

  • object
    uid: commonEvent

    Common event message properties.

  • object allOf
    uid: authRequiredEvent
  • object allOf
    uid: authRequestMsg
  • object allOf
    uid: authMsg
  • object allOf
    uid: versionMsg
  • object allOf
    uid: versionInfoMsg
  • object allOf
    uid: systemCmdMsg
  • object allOf
    uid: getSystemInfoMsg
  • object allOf
    uid: systemInfoMsg
  • object allOf
    uid: getFactoryResetTokenMsg
  • object allOf
    uid: factoryResetTokenMsg
  • object allOf
    uid: factoryResetMsg
  • object allOf
    uid: setApiAccessMsg
  • object allOf
    uid: getApiAccessMsg
  • object allOf
    uid: apiAccessMsg
  • object allOf
    uid: checkSystemUpdateMsg
  • object allOf
    uid: systemUpdateInfoMsg
  • object allOf
    uid: updateSystemMsg
  • object allOf
    uid: updateSystemResultMsg
  • object allOf
    uid: getSystemUpdateProgressMsg
  • object allOf
    uid: systemUpdateProgressMsg
  • object allOf
    uid: getPowerModeMsg
  • object allOf
    uid: powerModeMsg
  • object allOf
    uid: setPowerModeMsg
  • object allOf
    uid: getBatteryChargerMsg
  • object allOf
    uid: batteryChargerMsg
  • object allOf
    uid: updateBatteryChargerMsg
  • object allOf
    uid: getStandbyInhibitorsMsg
  • object allOf
    uid: inhibitorsMsg
  • object allOf
    uid: createStandbyInhibitorMsg
  • object allOf
    uid: inhibitorMsg
  • object allOf
    uid: delStandbyInhibitorMsg
  • object allOf
    uid: delAllStandbyInhibitorsMsg
  • object allOf
    uid: getAmbientLightMsg
  • object allOf
    uid: ambientLightMsg
  • object allOf
    uid: resetConfigurationMsg
  • object allOf
    uid: getConfigurationMsg
  • object allOf
    uid: configurationMsg
  • object allOf
    uid: getButtonCfgMsg
  • object allOf
    uid: setButtonCfgMsg
  • object allOf
    uid: buttonCfgMsg
  • object allOf
    uid: getDeviceCfgMsg
  • object allOf
    uid: setDeviceCfgMsg
  • object allOf
    uid: deviceCfgMsg
  • object allOf
    uid: getDisplayCfgMsg
  • object allOf
    uid: setDisplayCfgMsg
  • object allOf
    uid: displayCfgMsg
  • object allOf
    uid: getFeaturesCfgMsg
  • object allOf
    uid: setFeaturesCfgMsg
  • object allOf
    uid: featuresCfgMsg
  • object allOf
    uid: getHapticCfgMsg
  • object allOf
    uid: setHapticCfgMsg
  • object allOf
    uid: hapticCfgMsg
  • object allOf
    uid: getLocalizationCfgMsg
  • object allOf
    uid: setLocalizationCfgMsg
  • object allOf
    uid: localizationCfgMsg
  • object allOf
    uid: getTimezoneNamesMsg
  • object allOf
    uid: timezoneNamesMsg
  • object allOf
    uid: getLocalizationCountriesMsg
  • object allOf
    uid: localizationCountriesMsg
  • object allOf
    uid: getLocalizationLanguagesMsg
  • object allOf
    uid: localizationLanguagesMsg
  • object allOf
    uid: getNetworkCfgMsg
  • object allOf
    uid: setNetworkCfgMsg
  • object allOf
    uid: networkCfgMsg
  • object allOf
    uid: getSoftwareUpdateCfgMsg
  • object allOf
    uid: setSoftwareUpdateCfgMsg
  • object allOf
    uid: resetSoftwareUpdateCfgMsg
  • object allOf
    uid: softwareUpdateCfgMsg
  • object allOf
    uid: getPowerSavingCfgMsg
  • object allOf
    uid: setPowerSavingCfgMsg
  • object allOf
    uid: powerSavingCfgMsg
  • object allOf
    uid: getProfileCfgMsg
  • object allOf
    uid: setProfileCfgMsg
  • object allOf
    uid: profileCfgMsg
  • object allOf
    uid: getSoundCfgMsg
  • object allOf
    uid: setSoundCfgMsg
  • object allOf
    uid: soundCfgMsg
  • object allOf
    uid: getVoiceControlCfgMsg
  • object allOf
    uid: setVoiceControlCfgMsg
  • object allOf
    uid: voiceControlCfgMsg
  • object allOf
    uid: getVoiceAssistantsMsg
  • object allOf
    uid: voiceAssistantsMsg
  • object allOf
    uid: getEntityTypesMsg
  • object allOf
    uid: entityTypesMsg
  • object allOf
    uid: getEntityMsg
  • object allOf
    uid: getEntitiesMsg
  • object allOf
    uid: entitiesMsg
  • object allOf
    uid: getAvailableEntitiesMsg

    Retrieve the available entities provided by the integration instance.

  • object allOf
    uid: availableEntitiesMsg
  • object allOf
    uid: getEntityCommandsMsg
  • object allOf
    uid: entityCommandsMsg
  • object allOf
    uid: getEntityCommandMetadataMsg
  • object allOf
    uid: entityCommandMetadataMsg
  • object allOf
    uid: executeEntityCommandMsg
  • object allOf
    uid: entityMsg
  • object allOf
    uid: entityChangeEventMsg
  • object allOf
    uid: activityGroupChangeEventMsg
  • object allOf
    uid: updateEntityMsg
  • object allOf
    uid: deleteEntityMsg
  • object allOf
    uid: deleteEntitiesMsg
  • object allOf
    uid: getDockCountMsg
  • object allOf
    uid: dockCountMsg
  • object allOf
    uid: getDocksMsg
  • object allOf
    uid: docksMsg
  • object allOf
    uid: createDockMsg
  • object allOf
    uid: dockMsg
  • object allOf
    uid: deleteAllDocksMsg
  • object allOf
    uid: getDockMsg
  • object allOf
    uid: updateDockMsg
  • object allOf
    uid: dockConnectionCommandMsg
  • object allOf
    uid: deleteDockMsg
  • object allOf
    uid: dockCommandMsg
  • object allOf
    uid: getDockDiscoveryStatusMsg
  • object allOf
    uid: dockDiscoveryStatusMsg
  • object allOf
    uid: startDockDiscoveryMsg
  • object allOf
    uid: stopDockDiscoveryMsg
  • object allOf
    uid: getDockDiscoveryDeviceMsg
  • object allOf
    uid: dockDiscoveryDeviceMsg
  • object allOf
    uid: execCmdOnDiscoveredDockMsg
  • object allOf
    uid: dockSystemInfoMsg
  • object allOf
    uid: getDockSetupProcessesMsg
  • object allOf
    uid: dockSetupProcessesMsg
  • object allOf
    uid: createDockSetupMsg
  • object allOf
    uid: dockSetupStatusMsg
  • object allOf
    uid: stopAllDockSetupsMsg
  • object allOf
    uid: getDockSetupStatusMsg
  • object allOf
    uid: startDockSetupMsg
  • object allOf
    uid: stopDockSetupMsg
  • object allOf
    uid: wifiGetStatusMsg
  • object allOf
    uid: wifiStatusMsg
  • object allOf
    uid: wifiCommandMsg
  • object allOf
    uid: wifiScanStartMsg
  • object allOf
    uid: wifiScanStopMsg
  • object allOf
    uid: wifiGetScanStatusMsg
  • object allOf
    uid: wifiScanStatusMsg
  • object allOf
    uid: wifiGetAllNetworksMsg
  • object allOf
    uid: wifiNetworksMsg
  • object allOf
    uid: wifiAddNetworkMsg
  • object allOf
    uid: wifiDelAllNetworksMsg
  • object allOf
    uid: wifiGetNetworkMsg
  • object allOf
    uid: wifiNetworkMsg
  • object allOf
    uid: wifiUpdateNetworkMsg
  • object allOf
    uid: wifiNetworkCommandMsg
  • object allOf
    uid: wifiDelNetworkMsg
  • object allOf
    uid: wifiChangeEventMsg
  • object allOf
    uid: btPairingStartedEventMsg
  • object allOf
    uid: btPairingAuthRequestEventMsg
  • object allOf
    uid: btPairingCompleteEventMsg
  • object allOf
    uid: btPairingResponseMsg
  • object allOf
    uid: getProfilesMsg
  • object allOf
    uid: profilesMsg
  • object allOf
    uid: getProfileMsg
  • object allOf
    uid: profileMsg
  • object allOf
    uid: getActiveProfileMsg
  • object allOf
    uid: switchProfileMsg
  • object allOf
    uid: addProfileMsg
  • object allOf
    uid: updateProfileMsg
  • object allOf
    uid: deleteProfileMsg
  • object allOf
    uid: deleteAllProfilesMsg
  • object allOf
    uid: activeProfileChangeEventMsg
  • object allOf
    uid: profileChangeEventMsg
  • object allOf
    uid: getPagesMsg
  • object allOf
    uid: pagesMsg
  • object allOf
    uid: getPageMsg
  • object allOf
    uid: pageMsg
  • object allOf
    uid: addPageMsg
  • object allOf
    uid: updatePageMsg
  • object allOf
    uid: deletePageMsg
  • object allOf
    uid: deletePagesInProfileMsg
  • object allOf
    uid: getGroupsMsg
  • object allOf
    uid: groupsMsg
  • object allOf
    uid: getGroupMsg
  • object allOf
    uid: groupMsg
  • object allOf
    uid: addGroupMsg
  • object allOf
    uid: updateGroupMsg
  • object allOf
    uid: deleteGroupMsg
  • object allOf
    uid: deleteGroupsInProfileMsg
  • object allOf
    uid: getIntegrationStatusMsg
  • object allOf
    uid: integrationStatusMsg
  • object allOf
    uid: integrationCmdMsg
  • object allOf
    uid: integrationDriverCmdMsg
  • object allOf
    uid: getIntegrationDriverCountMsg
  • object allOf
    uid: integrationDriverCountMsg
  • object allOf
    uid: getIntegrationDriversMsg
  • object allOf
    uid: integrationDriversMsg
  • object allOf
    uid: registerIntegrationDriverMsg
  • object allOf
    uid: getIntegrationDriverMsg
  • object allOf
    uid: integrationDriverMsg
  • object allOf
    uid: updateIntegrationDriverMsg
  • object allOf
    uid: deleteIntegrationDriverMsg
  • object allOf
    uid: getIntegrationCountMsg
  • object allOf
    uid: integrationCountMsg
  • object allOf
    uid: getIntegrationsMsg
  • object allOf
    uid: integrationsMsg
  • object allOf
    uid: createIntegrationMsg
  • object allOf
    uid: integrationMsg
  • object allOf
    uid: getIntegrationMsg
  • object allOf
    uid: updateIntegrationMsg
  • object allOf
    uid: deleteIntegrationMsg
  • object allOf
    uid: configureEntityFromIntegrationMsg
  • object allOf
    uid: configureEntitiesFromIntegrationMsg
  • object allOf
    uid: getIntegrationDiscoveryStatusMsg
  • object allOf
    uid: integrationDiscoveryStatusMsg
  • object allOf
    uid: startIntegrationDiscoveryMsg
  • object allOf
    uid: stopIntegrationDiscoveryMsg
  • object allOf
    uid: getDiscoveredIntegrationDriverMsg
  • object allOf
    uid: discoveredIntegrationDriverMsg
  • object allOf
    uid: getDiscoveredIntgDriverMetadataMsg
  • object allOf
    uid: configureDiscoveredIntegrationDriverMsg
  • object allOf
    uid: getIntegrationSetupProcessesMsg
  • object allOf
    uid: integrationSetupProcessesMsg
  • object allOf
    uid: setupIntegrationMsg
  • object allOf
    uid: integrationSetupInfoMsg
  • object allOf
    uid: stopAllIntegrationSetupsMsg
  • object allOf
    uid: getIntegrationSetupStatusMsg
  • object allOf
    uid: setIntegrationUserDataMsg
  • object allOf
    uid: stopIntegrationSetupMsg
  • object allOf
    uid: getEventChannelsMsg
  • object allOf
    uid: eventChannelsMsg
  • object allOf
    uid: subscribeEventsMsg
  • object allOf
    uid: getEventSubscriptionsMsg
  • object allOf
    uid: unsubscribeEventsMsg
  • object allOf
    uid: eventSubscriptionsMsg
  • string anyOf
    uid: eventChannel

    The name of the event channel.

  • object allOf
    uid: warningEventMsg
  • object allOf
    uid: integrationDriverChangeEventMsg
  • object allOf
    uid: integrationChangeEventMsg
  • object allOf
    uid: integrationStateEventMsg
  • object allOf
    uid: configurationChangeEventMsg
  • object allOf
    uid: irLearningEventMsg
  • object allOf
    uid: dockChangeEventMsg
  • object allOf
    uid: dockStateEventMsg
  • object allOf
    uid: dockDiscoveryEventMsg
  • object allOf
    uid: dockSetupChangeEventMsg
  • object allOf
    uid: dockUpdateChangeEventMsg
  • object allOf
    uid: integrationDiscoveryEventMsg
  • object allOf
    uid: integrationSetupChangeEventMsg
  • object allOf
    uid: softwareUpdateEventMsg
  • object allOf
    uid: powerModeChangeEventMsg
  • object allOf
    uid: batteryStatusEventMsg
  • object allOf
    uid: ambientLightChangeEventMsg
  • object
    uid: error
  • object allOf
    uid: ping
  • object allOf
    uid: pong
  • object allOf
    uid: warningEvent
  • msgId
    integer
    >= 0uid: msgId

    Request message ID which is reflected in response message.

    Default value:0
  • object
    uid: paging

    Paging information for returned items.

  • object
    uid: pagination

    Returned pagination information.

  • object
    uid: versionInfo
  • object
    uid: systemInfo
  • object
    uid: enabledFilter

    Simple filter by enabled flag.

  • object
    uid: intgDriverFilter

    Filter for integration drivers.

  • object
    uid: availableEntityFilter

    Optional filters

  • availEntitiesFilter
    string
    uid: availEntitiesFilter

    Filter available entities

      Allowed values:
    • "NEW"
    • "CONFIGURED"
    • "ALL"
  • object
    uid: entityFilter

    Optional filters

  • object
    uid: entity

    Configured entity in the remote to be used in one or more profiles.

  • object
    uid: entityUpdate

    Entity update data.

    If used in an update operation:

    • Omitted properties will not change the configured value.
    • An empty icon value will remove the icon identifier.
    • entity_id, entity_type and integration_id cannot be changed.

    If returned in an entity_change event:

    • Additional properties from the regular entity object might be included as well.
  • object
    uid: available_entity

    Provided entity from an integration which can be configured to be used in the remote.

  • array<string>
    uid: entityFeatures
  • entityFeature
    string
    uid: entityFeature
  • entityCommand
    string
    uid: entityCommand

    Entity command identifier, as returned in the entity command metadata.

    This identifier may change at any time and may not be used for logic decisions in a client! If entity specific information is required, the entity object must be loaded from the entity_id.

  • entityType
    string
    uid: entityType

    Entity type.

      Allowed values:
    • "button"
    • "climate"
    • "cover"
    • "light"
    • "media_player"
    • "sensor"
    • "switch"
    • "activity"
    • "macro"
    • "remote"
    • "ir_emitter"
  • object
    uid: ActivityGroup

    An activity group creates a dependency between multiple activities. Switching between activities will consider the current state of the included entities and only turn-on or -off the required entities.

  • object
    uid: IncludedActivity

    Minimal activity object to show the activity in a user interface with it's friendly name and icon.

  • SequenceState
    string
    uid: SequenceState

    State of an Activity or Macro sequence:

    • RUNNING: Sequence is currently running
    • COMPLETED: Final state for a macro
    • ON: Final activity state for the on sequence
    • OFF: Final activity state for the off sequence
    • STOPPED: The sequence was aborted with a stop request
    • TIMEOUT: The sequence timed out and was aborted
    • ERROR: There was an error running the sequence and did not complete
      Allowed values:
    • "RUNNING"
    • "COMPLETED"
    • "ON"
    • "OFF"
    • "STOPPED"
    • "TIMEOUT"
    • "ERROR"
  • object
    uid: ActivityGroupOptions

    ๐Ÿ‘ทNot yet finalized!

    Activity group specific options, e.g. how delays are handled when switching between activities.

  • languageCode
    string
    must match: ^[a-z]{2}(_\w+)?$uid: languageCode

    Language culture code: starting with the two-letter ISO-639-1 code, followed by an optional ISO-3166 country code, separated by an underscore. Examples: en, en_UK, en_US, de, de_DE, de_CH etc.

  • countryCode
    string
    format: iso-3166uid: countryCode

    Two letter country code according to ISO-3166-1-alpha-2.

  • object
    uid: languageText

    Display text in the UI. An english text should always be provided as fallback option.

  • object
    uid: getConfigurationOptions

    Optional request parameters.

  • object
    uid: configuration
  • object
    uid: cfgButton
  • object
    uid: cfgButtonUpdate

    Button configuration model to update settings. Missing properties are not changed.

  • object
    uid: staticButtonColor

    Static color settings for all zones, if supported by the device.

  • object
    uid: cfgDevice
  • object
    uid: cfgDisplay
  • array<object>
    uid: cfgFeatures
  • object
    uid: cfgFeature
  • object
    uid: cfgFeatureUpdate
  • object
    uid: cfgHaptic
  • object
    uid: cfgLocalization
  • measurementUnit
    string
    uid: measurementUnit
      Allowed values:
    • "METRIC"
    • "US"
    • "UK"
  • object
    uid: cfgNetwork
  • object
    uid: cfgNetworkUpdate
  • object
    uid: cfgNetworkWs

    Optional expert settings for WebSocket (re-)connection handling.
    These settings are only intended for support issues and might change any time. Changed values are not supported and might make the system unstable!

  • object
    uid: cfgNetworkWoWlan

    Wake on WLAN settings

  • object
    uid: cfgPowerSaving
  • object
    uid: cfgProfile
  • object
    uid: cfgProfileUpdate
  • object
    uid: cfgSoftwareUpdate
  • object
    uid: cfgSound
  • object
    uid: cfgVoiceControl
  • voiceAssistant
    string
    uid: voiceAssistant

    ๐Ÿšง Supported voice assistants. TODO not yet implemented.

      Allowed values:
    • "None"
  • object
    uid: integrationStatus

    Integration instance status information. Intended to be used in a general overview of the integration drivers.

  • deviceState
    string
    uid: deviceState
      Allowed values:
    • "UNKNOWN"
    • "CONNECTING"
    • "CONNECTED"
    • "DISCONNECTED"
    • "ERROR"
  • driverState
    string
    uid: driverState
      Allowed values:
    • "NOT_CONFIGURED"
    • "IDLE"
    • "CONNECTING"
    • "ACTIVE"
    • "RECONNECTING"
    • "ERROR"
  • integrationState
    string
    uid: integrationState
      Allowed values:
    • "NOT_CONFIGURED"
    • "UNKNOWN"
    • "IDLE"
    • "CONNECTING"
    • "CONNECTED"
    • "DISCONNECTED"
    • "RECONNECTING"
    • "ACTIVE"
    • "ERROR"
  • integrationDriverType
    string
    uid: integrationDriverType
      Allowed values:
    • "LOCAL"
    • "EXTERNAL"
  • object
    uid: integrationDriverInfo

    Summary data of an integration driver intended for overview screens.

  • object
    uid: integrationDriver

    Integration driver model.

    A driver represents the communication aspect of an integration. E.g. how one can connect to it and which API version it supports.

    One driver can provide multiple Integration instances. In the integration API they are referred to as multi-device integrations and use the optional device_id property where required. If a driver only provides a single instance, which is usually the default use case, then the device_id is not used (or set to the default value main).

  • object
    uid: driverDeveloper

    Optional information about the integration developer.

  • object
    uid: integrationDriverUpdate

    Integration driver update model. This model corresponds to the IntegrationDriver model except there are no required properties to allow patch updates.

    • Specified properties will update the current values.
    • An empty value will delete the currently set property.
    • For the create operation, the driver_id identifier can be specified by the client, but it needs to be unique among all drivers. If omitted, a UUID will be assigned.
      A manually assigned, short, human-readable identifier is recommended for better recognizability.
  • object
    uid: integration

    An integration instance represents a configured integration driver.

    TODO add connection state?

  • object
    uid: integrationUpdate

    Integration instance update model. This model corresponds to the Integration model except there are no required properties to allow patch updates.

    • Specified properties will update the current values.
    • An empty value will delete a set property.
    • device_id is only required for multi-device integrations.
  • object
    uid: IntegrationDiscoveryStatus
  • object
    uid: CreateIntegrationSetup
  • object
    uid: IntegrationSetupInfo

    Integration setup state

  • object
    uid: entityChange

    The new_state property is omitted for event_type = delete.
    The client should reload all entity data, if only event_type is present.

  • object
    uid: activityGroupChange

    The new_state property is omitted for event_type = delete.
    The client should reload all activity group data, if only event_type is present.

  • object
    uid: activeProfileChange

    The new_state.profile object contains additional profile data of the new active profile_id.

  • object
    uid: profileChange

    The new_state property is omitted for event_type = delete.

  • object
    uid: integrationDriverChange

    The new_state property is omitted for event_type = delete.

  • object
    uid: integrationChange

    The new_state property is omitted for event_type = delete.

  • object
    uid: integrationStateData
  • defaultChangeEventType
    string
    uid: defaultChangeEventType
      Allowed values:
    • "change"
    • "new"
    • "delete"
  • object
    uid: configurationChange
  • object
    uid: irLearning
  • object
    uid: irLearningCode
  • dockId
    string
    format: ^[a-zA-Z0-9\-\.]+$[ 1 .. 64 ] charactersuid: dockId

    Dock identifier

  • dockName
    string
    [ 1 .. 40 ] charactersuid: dockName

    User assignable friendly name to use instead of dock_id (service name).

  • dockUrl
    string
    <= 64 charactersuid: dockUrl

    Dock WebSocket URL to override auto-discovery from the service name in dock_id.

  • dockToken
    string
    format: password[ 1 .. 40 ] charactersuid: dockToken

    Access token

  • object
    uid: dockFilter

    Optional filters

  • object
    uid: dockChangeData

    The new_state property is omitted for event_type = delete.

  • object
    uid: dockConfiguration
  • object
    uid: dockConfigurationRequest
  • object
    uid: dockUpdateRequest
  • object
    uid: dockSystemInfo
  • object
    uid: dockStateData
  • dockState
    string
    uid: dockState
      Allowed values:
    • "IDLE"
    • "CONNECTING"
    • "ACTIVE"
    • "RECONNECTING"
    • "ERROR"
  • object
    uid: dockDiscovery
  • object
    uid: dockDiscoveryInformation
  • discoveryType
    string
    uid: discoveryType

    Device discovery type:

    • BT: Bluetooth
    • NET: LAN or WAN network
      Allowed values:
    • "BT"
    • "NET"
  • object oneOf
    uid: createDockSetup
  • object
    uid: dockSetup

    Dock setup data

  • object
    uid: dockSetupFromDiscovery
  • object
    uid: dockSetupInfo

    Dock setup state

  • object
    uid: dockSetupChange
  • dockSetupState
    string
    uid: dockSetupState
      Allowed values:
    • "NEW"
    • "CONFIGURING"
    • "UPLOADING"
    • "RESTARTING"
    • "OK"
    • "ERROR"
  • dockSetupError
    string
    uid: dockSetupError
      Allowed values:
    • "NONE"
    • "NOT_FOUND"
    • "CONNECTION_ERROR"
    • "CONNECTION_REFUSED"
    • "AUTHORIZATION_ERROR"
    • "TIMEOUT"
    • "ABORT"
    • "PERSISTENCE_ERROR"
    • "OTHER"
  • object
    uid: dockUpdateChange
  • object
    uid: AvailableSystemUpdateResponse
  • object
    uid: AvailableSystemUpdate
  • UpdateChannel
    string
    uid: UpdateChannel
      Allowed values:
    • "STABLE"
    • "TESTING"
    • "DEVELOPMENT"
  • UpdateDownloadState
    string
    uid: UpdateDownloadState

    Download status:

    • PENDING: update is scheduled to download
    • DOWNLOADING: update is currently downloading
    • DOWNLOADED: update has been downloaded and is ready to be installed
    • ERROR: download failed
      Allowed values:
    • "PENDING"
    • "DOWNLOADING"
    • "DOWNLOADED"
    • "ERROR"
  • object
    uid: SystemUpdateResponse
  • object
    uid: softwareUpdateEvent
  • object
    uid: powerModeChangeEvent
  • object
    uid: batteryStatus
  • object
    uid: SystemUpdateProgress
  • SystemUpdateState
    string
    uid: SystemUpdateState
      Allowed values:
    • "IDLE"
    • "START"
    • "RUN"
    • "SUCCESS"
    • "FAILURE"
    • "DOWNLOAD"
    • "DONE"
    • "SUB_PROCESS"
    • "PROGRESS"
  • object
    uid: integrationDiscoveryEvent
  • object
    uid: integrationDiscoveryInformation
  • object
    uid: integrationSetupChange
  • integrationSetupState
    string
    uid: integrationSetupState
    • SETUP: setup in progress
    • WAIT_USER_ACTION: setup flow is waiting for user input. See require_user_action for requested input.
    • OK: setup finished successfully
    • ERROR: setup error
      Allowed values:
    • "SETUP"
    • "WAIT_USER_ACTION"
    • "OK"
    • "ERROR"
  • integrationSetupError
    string
    uid: integrationSetupError

    More detailed error reason for state: ERROR condition.

      Allowed values:
    • "NONE"
    • "NOT_FOUND"
    • "CONNECTION_REFUSED"
    • "AUTHORIZATION_ERROR"
    • "TIMEOUT"
    • "OTHER"
  • object
    uid: ConfirmationPage

    Confirmation screen

  • object
    uid: SettingsPage

    Settings definition page, e.g. to configure an integration driver.

  • object
    uid: Setting

    An input setting is of a specific type defined in field.type which defines how it is presented to the user.

    Inspired by the Homey SDK settings concept.

  • object
    uid: SettingTypeNumber

    Number input with optional min, max, steps and decimals properties. The default value must be specified in value. An optional unit of the number setting can be specified in units, which will be displayed next to the input field.

  • object
    uid: SettingTypeText

    Single line of text input.

    TODO: format specifier for e.g. email, url, date, datetime etc.?

  • object
    uid: SettingTypeTextArea

    Multi-line text input, e.g. for providing a description.

  • object
    uid: SettingTypePassword

    Password or pin entry field with the input text hidden from the user. Otherwise the same as text input.

  • object
    uid: SettingTypeCheckbox

    Checkbox setting with true / false values.

  • object
    uid: SettingTypeDropdown

    Dropdown setting to pick a single value from a list. All values must be strings.

  • object
    uid: SettingTypeLabel

    Additional read-only text for information purpose between other settings. Supports Markdown formatting.

  • object
    uid: SettingsValues

    User input result of a SettingsPage as key values.

    • key: id of the field
    • value: entered user value as string. This is either the entered text or number, selected checkbox state or the selected dropdown item id.
      โš ๏ธ Non native string values as numbers or booleans are represented as string values!
  • description
    string
    <= 255 charactersuid: description

    Optional description

  • array<object>
    uid: groups
  • object
    uid: group

    The shown group switch in the UI is automatically determined by the capabilities of the group's entities.

  • object
    uid: groupData
  • iconIdentifier
    string
    format: ^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$<= 255 charactersuid: iconIdentifier

    Optional icon identifier. The identifier consists of a prefix and a resource identifier, separated by :.
    Available prefixes:

    • uc: - integrated icon font
    • custom: - custom icon resource
    • ctv: - custom TV icon resource

    Other prefixes might be rejected by the service.

    An empty identifier, while updating the object, removes the existing icon.

  • imageIdentifier
    string
    format: ^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$<= 255 charactersuid: imageIdentifier

    Optional image identifier. The identifier consists of a prefix and a resource identifier, separated by :.
    Available prefixes:

    • custom: - custom image resource

    Other prefixes might be rejected by the service.

    An empty identifier, while updating the object, removes the existing image.

  • name
    string
    [ 1 .. 50 ] charactersuid: name
  • array<object>
    uid: pages
  • object
    uid: page
  • object oneOf
    uid: pageItem
  • object
    uid: pageData

    Profile page data to create or update an existing page.

  • array<object>
    uid: profiles
  • object
    uid: profile
  • object
    uid: profileData

    Profile data to create or modify a profile. Missing properties are not updated when modifying an existing profile.

  • adminPin
    string
    <= 20 charactersuid: adminPin

    Optional administrator pin.

  • simpleId
    string
    format: ^[a-zA-Z0-9\-_\.]+$[ 1 .. 36 ] charactersuid: simpleId

    Simple string identifier, also usable as URL parameter or file identifier.

  • driverId
    string
    format: ^[a-zA-Z0-9\-_]+$[ 1 .. 36 ] charactersuid: driverId

    Unique integration driver identifier, e.g. hass, homey, etc.

  • integrationId
    string
    format: ^[a-zA-Z0-9\-_\.]+$[ 1 .. 73 ] charactersuid: integrationId

    Unique integration instance identifier. Automatically created by the system when creating a new instance from a driver.

  • deviceId
    string
    format: ^[a-zA-Z0-9\-_]+$[ 1 .. 36 ] charactersuid: deviceId

    Device identifier for multi-device integrations only.

  • entityId
    string
    format: ^[a-zA-Z0-9\-_\.]+$[ 1 .. 110 ] charactersuid: entityId

    UC remote entity identifier.

  • intgAuthMethod
    string
    uid: intgAuthMethod

    Integration driver authentication method if a token is required.

    The JSON auth message is used if a token is configured but no authentication method is set.

      Allowed values:
    • "HEADER"
    • "MESSAGE"
  • object
    uid: ApScanStatus
  • object
    uid: AccessPointScan
  • object
    uid: WifiStatus
  • object
    uid: CreateWifiNetwork
  • object
    uid: ModifyWifiNetwork
  • array<object>
    uid: SavedNetworks
  • object
    uid: SavedNetwork

    A saved network configuration (known network)

  • WpaState
    string
    uid: WpaState
    • UNKNOWN: Unknown state. The driver returned a state which could not be handled.
    • ERROR: Error retrieving state information.
    • DISCONNECTED: This state indicates that client is not associated, but is likely to start looking for an access point. This state is entered when a connection is lost.
    • INTERFACE_DISABLED: This state is entered if the network interface is disabled. The driver refuses any new operations that would use the radio until the interface has been enabled.
    • INACTIVE: This state is entered if there are no enabled networks in the configuration. The driver is not trying to associate with a new network and external interaction (e.g. add or enable a network) is needed to start association.
    • SCANNING: Scanning for a network.
    • AUTHENTICATED: Trying to authenticate with a BSS/SSID.
    • ASSOCIATING: Trying to associate with a BSS/SSID.
    • ASSOCIATED: Association completed.
    • FOUR_WAY_HANDSHAKE: WPA 4-Way Key Handshake in progress.
    • GROUP_HANDSHAKE: WPA Group Key Handshake in progress.
    • COMPLETED: All authentication completed.
      Allowed values:
    • "UNKNOWN"
    • "ERROR"
    • "DISCONNECTED"
    • "INTERFACE_DISABLED"
    • "INACTIVE"
    • "SCANNING"
    • "AUTHENTICATED"
    • "ASSOCIATING"
    • "ASSOCIATED"
    • "FOUR_WAY_HANDSHAKE"
    • "GROUP_HANDSHAKE"
    • "COMPLETED"
  • WifiCmd
    string
    uid: WifiCmd
      Allowed values:
    • "DISCONNECT"
    • "RECONNECT"
    • "REASSOCIATE"
    • "ENABLE_ALL_NETWORKS"
    • "DISABLE_ALL_NETWORKS"
  • WifiNetworkCmd
    string
    uid: WifiNetworkCmd
      Allowed values:
    • "ENABLE"
    • "DISABLE"
    • "SELECT"
  • NetworkState
    string
    uid: NetworkState
      Allowed values:
    • "CONNECTED"
    • "OUT_OF_RANGE"
    • "DISABLED"
    • "TEMPORARY_DISABLED"
  • object
    uid: WifiChange
  • WifiEvent
    string
    uid: WifiEvent

    WiFi event:

    • CONNECTED: Authentication completed successfully and data connection enabled.
    • DISCONNECTED: Disconnected from access point and data connection not available.
    • SCAN_STARTED: Network scan started.
    • SCAN_COMPLETED: New network scan results available.
    • SCAN_FAILED: Network scanning failed.
    • NETWORK_NOT_FOUND: No suitable network was found.
    • WRONG_KEY: Authentication failure due to an invalid pre-shared key.
    • NETWORK_ADDED: A new network profile was added.
    • NETWORK_REMOVED: A network profile was removed.
      Allowed values:
    • "CONNECTED"
    • "DISCONNECTED"
    • "SCAN_STARTED"
    • "SCAN_COMPLETED"
    • "SCAN_FAILED"
    • "NETWORK_NOT_FOUND"
    • "WRONG_KEY"
    • "NETWORK_ADDED"
    • "NETWORK_REMOVED"
  • object
    uid: BtPairingStarted
  • object
    uid: BtPairingAuthRequest
  • object
    uid: BtPairingComplete
  • BtBondingSecurityType
    string
    uid: BtBondingSecurityType

    Bonding security type:

    • JustWorks: Automatic pairing, peripheral only needs to confirm pairing request from central.
    • DisplayNumber: Peripheral must display number for the central to confirm.
    • NumericComparison: Peripheral must confirm or declined if the numeric value matches the displayed number on the central.
    • PasskeyInput: Peripheral must enter displayed passkey on central.
      Allowed values:
    • "JUST_WORKS"
    • "DISPLAY_NUMBER"
    • "NUMERIC_COMPARISON"
    • "PASSKEY_INPUT"
  • object allOf
    uid: BtPairingResponse

    Response to a pairing request.

    • Passkey request: either provide the passkey entered by the user, decline it with confirm: false.
    • NumericComparison request: confirm or decline with confirm: true | false.
  • object
    uid: BtPeer

    Information about the (paired) peer.

  • BtAddressType
    string
    uid: BtAddressType

    Address type:

    • LE_PUBLIC: Public device address
    • LE_RANDOM: Random device address
    • LE_PUBLIC_IDENTITY: Public identity address (corresponds to resolved private address)
    • LE_RANDOM_IDENTITY: Random (static) identity address (corresponds to resolved private address)
    • UNKNOWN: Address could not be determined, or an error occurred
      Allowed values:
    • "LE_PUBLIC"
    • "LE_RANDOM"
    • "LE_PUBLIC_IDENTITY"
    • "LE_RANDOM_IDENTITY"
    • "UNKNOWN"
  • PowerMode
    string
    uid: PowerMode
      Allowed values:
    • "NORMAL"
    • "IDLE"
    • "LOW_POWER"
    • "SUSPEND"
  • PowerStatus
    string
    uid: PowerStatus
      Allowed values:
    • "CHARGING"
    • "DISCHARGING"
    • "NOT_CHARGING"
    • "FULL"
  • object
    uid: BatteryCharger
  • object
    uid: BatteryChargerUpdate
  • object
    uid: AmbientLight
  • array<object>
    uid: Inhibitors
  • object
    uid: Inhibitor
  • InhibitMode
    string
    uid: InhibitMode
      Allowed values:
    • "BLOCK"
    • "DELAY"
  • object
    uid: CreateStandbyInhibitor